001: /*
002:
003: Derby - Class org.apache.derby.iapi.services.cache.CacheManager
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.iapi.services.cache;
023:
024: import org.apache.derby.iapi.error.StandardException;
025: import org.apache.derby.iapi.services.daemon.DaemonService;
026:
027: import org.apache.derby.iapi.util.Matchable;
028: import org.apache.derby.iapi.util.Operator;
029:
030: public interface CacheManager {
031:
032: /**
033: * @return the current maximum size of the cache.
034: */
035: public long getMaximumSize();
036:
037: /**
038: * Change the maximum size of the cache. If the size is decreased then cache entries
039: * will be thrown out.
040: *
041: * @param newSize the new maximum cache size
042: *
043: * @exception StandardException Cloudscape Standard error policy
044: */
045: public void resize(long newSize) throws StandardException;
046:
047: /**
048: Find an object in the cache.
049: <p>
050: Find an object in the cache that matches the key provided using the equals()
051: method, i.e. the return Cacheable will have getIdentifier.equals(key) true.
052: If the object does not exist in the cache it will be added by one of:
053: <UL>
054: <LI>creating a new holder object and calling its initParameter() method and then its
055: setIdentity() method with key as the parameter.
056: <LI>Calling clearIdentity() on an holder object in the clean state and then calling its
057: setIdentity() method with key as the parameter.
058: <LI>Calling clean() on a dirty holder object and then calling clearIdentity() on an
059: holder object in the clean state and then calling its setIdentity() method with key
060: as the parameter.
061: </UL>
062: In all cases the setIdentity() method is called with forCreate set to false.
063: <BR>
064: The returned object is kept, i.e. its identity will not change, until the release()
065: method is called. The release() method must be called after the caller is finished
066: with the object and throw away the reference to it, e.g.
067: <PRE>
068: Page p = (Page) pageCache.find(pageKey);
069:
070: // do stuff with p
071:
072: // release p
073: pageCache.release(p);
074: p = null;
075:
076: </PRE>
077:
078: @return A reference to an object in the cache, or null if the object cannot be found.
079:
080: @exception StandardException Standard Cloudscape error policy.
081:
082: @see Cacheable#setIdentity
083:
084: */
085: public Cacheable find(Object key) throws StandardException;
086:
087: /**
088: Find an object in the cache.
089: <p>
090: Find an object in the cache that matches the key provided using the equals()
091: method, i.e. the return Cacheable will have getIdentifier.equals(key) true.
092: If a matching object does not exist in the cache, null is returned.
093: <BR>
094: The returned object is kept, i.e. its identity will not change, until the release()
095: method is called. The release() method must be called after the caller is finished
096: with the object and throw away the reference to it, e.g.
097: <PRE>
098: Page p = (Page) pageCache.findCached(pageKey);
099: if (p != null) {
100:
101: // do stuff with p
102:
103: // release p
104: pageCache.release(p);
105: p = null;
106: }
107:
108: </PRE>
109: @exception StandardException Standard Cloudscape error policy.
110: */
111: public Cacheable findCached(Object key) throws StandardException;
112:
113: /**
114: * Determine whether a key is in the cache.
115: *
116: * <b>WARNING:</b> This method does not keep a lock on the entry or the cache, so
117: * the return value could be made incorrect by the time that this method returns.
118: * Therefore this method should only be used for statistical purposes.
119: */
120: public boolean containsKey(Object key);
121:
122: /**
123: * Mark a set of entries as having been used. Normally this is done as a side effect
124: * of find() or findCached. If the entry has been replaced then this method
125: * does nothing.
126: *
127: * @param keys the key of the used entry.
128: */
129: public void setUsed(Object[] keys);
130:
131: /**
132: Create an object in the cache. The resulting object will match the key provided using the equals()
133: method, i.e. the return Cacheable will have getIdentifier.equals(key) true.
134: If an object that matches the key already exists in the cache then
135: an exception is thrown.
136: <BR>
137: The object will be added by one of:
138: <UL>
139: <LI>creating a new holder object and calling its initParameter() method and then its
140: createIdentity() method with key as the parameter.
141: <LI>Calling clearIdentity() on an holder object in the clean state and then calling its
142: createIdentity() method with key as the parameter.
143: <LI>Calling clean() on a dirty holder object and then calling clearIdentity() on an
144: holder object in the clean state and then calling its createIdentity() method with key
145: as the parameter.
146: </UL>
147: In all cases the setIdentity() method is called with the createParameter as the second
148: argument.
149: If the object cannot be created then an exception is thrown by createIdentity.
150: <BR>
151: The returned object is kept, i.e. its identity will not change, until the release()
152: method is called. The release() method must be called after the caller is finished
153: with the object and throw away the reference to it, e.g.
154: <PRE>
155: Page p = (Page) pageCache.create(pageKey, createType);
156:
157: // do stuff with p
158:
159: // release p
160: pageCache.release(p);
161: p = null;
162:
163: </PRE>
164:
165: @return A reference to an object in the cache.
166:
167: @exception StandardException Standard Cloudscape error policy.
168:
169: @see Cacheable#createIdentity
170:
171: */
172: public Cacheable create(Object key, Object createParameter)
173: throws StandardException;
174:
175: /**
176: Release a Cacheable object previously found with find() or findCached().
177: After this call the caller must throw away the reference to item.
178:
179: */
180: public void release(Cacheable entry);
181:
182: /**
183: Delete and remove an object from the cache. It is up to the user of the cache
184: to provide synchronization of some form that ensures that only one caller
185: executes remove() on a cached object.
186: <BR>
187: The object must have previously been found with find() or findCached().
188: The item will be placed into the NoIdentity
189: state through clean(true) (if required) and clearIdentity(). The removal of the
190: object will be delayed until it is not kept by anyone. Objects that are in the
191: to be removed state can still be found through find() and findCached()
192: until their keep count drops to zero. This call waits until the object
193: has been removed.
194: <BR>
195: After this call the caller must throw away the reference to item.
196:
197: @exception StandardException Standard Cloudscape error policy.
198: */
199: public void remove(Cacheable entry) throws StandardException;
200:
201: /**
202: Place all objects in their clean state by calling their clean method
203: if they are dirty. This method guarantees that all objects that existed
204: in the cache at the time of the call are placed in the clean state
205: sometime during this call. Objects that are added to the cache during
206: this call or objects that are dirtied during this call (by other
207: callers) are not guaranteed to be clean once this call returns.
208:
209: @see Cacheable#clean
210: @see Cacheable#isDirty
211:
212: @exception StandardException Standard Cloudscape error policy.
213: */
214: public void cleanAll() throws StandardException;
215:
216: /**
217: Clean all objects that match the partialKey (or exact key).
218: Any cached object that results in the partialKey.equals(Object)
219: method returning true when passed the cached object will be cleaned.
220: <P>
221: In order to clean more than one object the Cacheable equals method must
222: be able to handle a partial key, e.g. a page has PageKey but a clean
223: may pass a ContainerKey which will discard all pages in that container.
224:
225: @exception StandardException Standard Cloudscape error policy.
226: */
227: public void clean(Matchable partialKey) throws StandardException;
228:
229: /**
230: Age as many objects as possible out of the cache.
231: This call is guaranteed not to block.
232: It is not guaranteed to leave the cache empty.
233:
234: <BR>
235: It is guaranteed that all unkept, clean objects will be
236: removed from the cache.
237:
238: @see Cacheable#clean
239: @see Cacheable#clearIdentity
240:
241:
242: */
243: public void ageOut();
244:
245: /**
246: Shutdown the cache. This call stops the cache returning
247: any more valid references on a find() or findCached() call,
248: and then cleanAll() and ageOut() are called. The cache remains
249: in existence until the last kept object has been unkept.
250:
251: @exception StandardException Standard Cloudscape error policy.
252:
253: */
254: public void shutdown() throws StandardException;
255:
256: /**
257: This cache can use this DaemonService if it needs some work to be done
258: int he background
259: */
260: public void useDaemonService(DaemonService daemon);
261:
262: /**
263: Discard all objects that match the partialKey (or exact key).
264: Any cached object that results in the partialKey.equals(Object)
265: method returning true when passed the cached object will be thrown out of the cache
266: if and only if it is not in use. The Cacheable
267: will be discarded without its clean method being called.
268: <P>
269: If partialKey is null, it matches all objects. This is a way to
270: discard all objects from the cache in case of emergency shutdown.
271: <P>
272: In order to discard more than one object the Cacheable equals method must be able to handle
273: a partial key, e.g. a page has PageKey but a discard may pass a ContainerKey which will discard
274: all pages in that container.
275: <P>
276: @return true if discard has successful gotten rid of all objects that
277: match the partial or exact key. False if some objects that matches
278: were not gotten rid of because it was kept.
279: */
280: public boolean discard(Matchable partialKey);
281:
282: /**
283: Report the number of items in use (with Identity) in this cache.
284: */
285: public int getNumberInUse();
286:
287: /**
288: Return statistics about cache that may be implemented.
289: **/
290: public long[] getCacheStats();
291:
292: /**
293: reset the cache statistics to 0.
294: **/
295: public void resetCacheStats();
296:
297: /**
298: * Perform an operation on (approximately) all entries that matches the filter,
299: * or all entries if the filter is null. Entries that are added while the
300: * cache is being scanned might or might not be missed.
301: *
302: * @param filter
303: * @param operator
304: */
305: public void scan(Matchable filter, Operator operator);
306: }
|