001: /*
002:
003: Derby - Class org.apache.derby.impl.store.access.CacheableConglomerate
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.impl.store.access;
023:
024: import java.util.Properties;
025: import org.apache.derby.iapi.services.cache.Cacheable;
026: import org.apache.derby.iapi.services.cache.CacheManager;
027: import org.apache.derby.iapi.services.sanity.SanityManager;
028: import org.apache.derby.iapi.error.StandardException;
029: import org.apache.derby.iapi.store.access.conglomerate.Conglomerate;
030:
031: /**
032: The CacheableConglomerate implements a single item in the cache used by
033: the Conglomerate directory to cache Conglomerates. It is simply a wrapper
034: object for the conglomid and Conglomerate object that is read from the
035: Conglomerate Conglomerate. It is a wrapper rather than extending
036: the conglomerate implementations because we want to cache all conglomerate
037: implementatations: (ie. Heap, B2I, ...).
038:
039: References to the Conglomerate objects cached by this wrapper will be handed
040: out to callers. When this this object goes out of cache callers may still
041: have references to the Conglomerate objects, which we are counting on java
042: to garbage collect. The Conglomerate Objects never change after they are
043: created.
044:
045: **/
046:
047: class CacheableConglomerate implements Cacheable {
048: private Long conglomid;
049: private Conglomerate conglom;
050:
051: /* Constructor */
052: CacheableConglomerate() {
053: }
054:
055: /*
056: ** protected Methods of CacheableConglomerate:
057: */
058: protected Conglomerate getConglom() {
059: return (this .conglom);
060: }
061:
062: /*
063: ** Methods of Cacheable:
064: */
065:
066: /**
067: Set the identity of the object to represent an item that already exists,
068: e.g. an existing container.
069: The object will be in the No Identity state,
070: ie. it will have just been created or clearIdentity() was just called.
071: <BR>
072: The object must copy the information out of key, not just store a reference to key.
073: After this call the expression getIdentity().equals(key) must return true.
074: <BR>
075: If the class of the object needs to change (e.g. to support a different format)
076: then the object should create a new object, call its initParameter() with the parameters
077: the original object was called with, set its identity and return a reference to it. The cache
078: manager will discard the reference to the old object.
079: <BR>
080: If an exception is thrown the object must be left in the no-identity state.
081:
082: <BR> MT - single thread required - Method must only be called be cache manager
083: and the cache manager will guarantee only one thread can be calling it.
084:
085: @return an object reference if the object can take on the identity, null otherwise.
086:
087: @exception StandardException Standard Cloudscape Policy
088:
089: @see CacheManager#find
090:
091: */
092: public Cacheable setIdentity(Object key) throws StandardException {
093: if (SanityManager.DEBUG) {
094: SanityManager.THROWASSERT("not supported.");
095: }
096:
097: return (null);
098: }
099:
100: /**
101: * Create a new item and set the identity of the object to represent it.
102: * The object will be in the No Identity state,
103: * ie. it will have just been created or clearIdentity() was just called.
104: * <BR>
105: * The object must copy the information out of key, not just store a
106: * reference to key. After this call the expression
107: * getIdentity().equals(key) must return true.
108: * <BR>
109: * If the class of the object needs to change (e.g. to support a different
110: * format) then the object should create a new object, call its
111: * initParameter() with the parameters the original object was called with,
112: * set its identity and return a reference to it. The cache manager will
113: * discard the reference to the old object.
114: * <BR>
115: * If an exception is thrown the object must be left in the no-identity
116: * state.
117: * <BR> MT - single thread required - Method must only be called be cache
118: * manager and the cache manager will guarantee only one thread can be
119: * calling it.
120: *
121: * @return an object reference if the object can take on the identity,
122: * null otherwise.
123: *
124: * @exception StandardException If forCreate is true and the object cannot
125: * be created.
126: *
127: * @see CacheManager#create
128: **/
129: public Cacheable createIdentity(Object key, Object createParameter)
130: throws StandardException {
131: if (SanityManager.DEBUG) {
132: SanityManager.ASSERT(key instanceof Long,
133: "key is not instanceof Long");
134: SanityManager.ASSERT(
135: createParameter instanceof Conglomerate,
136: "createParameter is not instanceof Conglomerate");
137: }
138:
139: this .conglomid = (Long) key;
140: this .conglom = ((Conglomerate) createParameter);
141:
142: return (this );
143: }
144:
145: /**
146: Put the object into the No Identity state.
147:
148: <BR> MT - single thread required - Method must only be called be cache manager
149: and the cache manager will guarantee only one thread can be calling it.
150:
151: */
152: public void clearIdentity() {
153: this .conglomid = null;
154: this .conglom = null;
155: }
156:
157: /**
158: Get the identity of this object.
159:
160: <BR> MT - thread safe.
161:
162: */
163: public Object getIdentity() {
164: return (this .conglomid);
165: }
166:
167: /**
168: Returns true of the object is dirty. Will only be called when the object is unkept.
169:
170: <BR> MT - thread safe
171:
172: */
173: public boolean isDirty() {
174: return (false);
175: }
176:
177: /**
178: Clean the object.
179: It is up to the object to ensure synchronization of the isDirty()
180: and clean() method calls.
181: <BR>
182: If forRemove is true then the
183: object is being removed due to an explict remove request, in this case
184: the cache manager will have called this method regardless of the
185: state of the isDirty()
186:
187: <BR>
188: If an exception is thrown the object must be left in the clean state.
189:
190: <BR> MT - thread safe - Can be called at any time by the cache manager, it is the
191: responsibility of the object implementing Cacheable to ensure any users of the
192: object do not conflict with the clean call.
193:
194: @exception StandardException Standard Cloudscape error policy.
195:
196: */
197: public void clean(boolean forRemove) throws StandardException {
198: }
199: }
|