CacheManager


1   /*
2   
3      Derby - Class org.apache.derby.iapi.services.cache.CacheManager
4   
5      Licensed to the Apache Software Foundation (ASF) under one or more
6      contributor license agreements.  See the NOTICE file distributed with
7      this work for additional information regarding copyright ownership.
8      The ASF licenses this file to you under the Apache License, Version 2.0
9      (the "License"); you may not use this file except in compliance with
10     the License.  You may obtain a copy of the License at
11  
12        http://www.apache.org/licenses/LICENSE-2.0
13  
14     Unless required by applicable law or agreed to in writing, software
15     distributed under the License is distributed on an "AS IS" BASIS,
16     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17     See the License for the specific language governing permissions and
18     limitations under the License.
19  
20   */
21  
22  package org.apache.derby.iapi.services.cache;
23  
24  import org.apache.derby.iapi.error.StandardException;
25  import org.apache.derby.iapi.services.daemon.DaemonService;
26  
27  import org.apache.derby.iapi.util.Matchable;
28  import org.apache.derby.iapi.util.Operator;
29  
30  public interface CacheManager {
31  
32      /**
33       * @return the current maximum size of the cache.
34       */
35      public long getMaximumSize();
36  
37      /**
38       * Change the maximum size of the cache. If the size is decreased then cache entries
39       * will be thrown out.
40       *
41       * @param newSize the new maximum cache size
42       *
43       * @exception StandardException Cloudscape Standard error policy
44       */
45      public void resize( long newSize) throws StandardException;
46  
47      /**
48          Find an object in the cache.
49          <p>
50          Find an object in the cache that matches the key provided using the equals()
51          method, i.e. the return Cacheable will have getIdentifier.equals(key) true.
52          If the object does not exist in the cache it will be added by one of:
53          <UL>
54          <LI>creating a new holder object and calling its initParameter() method and then its
55          setIdentity() method with key as the parameter.
56          <LI>Calling clearIdentity() on an holder object in the clean state and then calling its
57          setIdentity() method with key as the parameter.
58          <LI>Calling clean() on a dirty holder object and then calling clearIdentity() on an
59          holder object in the clean state and then calling its setIdentity() method with key
60          as the parameter.
61          </UL>
62          In all cases the setIdentity() method is called with forCreate set to false. 
63          <BR>
64          The returned object is kept, i.e. its identity will not change, until the release()
65          method is called. The release() method must be called after the caller is finished
66          with the object and throw away the reference to it, e.g.
67          <PRE>
68              Page p = (Page) pageCache.find(pageKey);
69  
70              // do stuff with p
71  
72              // release p
73              pageCache.release(p);
74              p = null;
75              
76          </PRE>
77  
78          @return A reference to an object in the cache, or null if the object cannot be found.
79  
80          @exception StandardException Standard Cloudscape error policy.
81  
82          @see Cacheable#setIdentity
83  
84      */
85      public Cacheable find(Object   key) throws StandardException;
86  
87      /**
88          Find an object in the cache.
89          <p>
90          Find an object in the cache that matches the key provided using the equals()
91          method, i.e. the return Cacheable will have getIdentifier.equals(key) true.
92          If a matching object does not exist in the cache, null is returned.
93          <BR>
94          The returned object is kept, i.e. its identity will not change, until the release()
95          method is called. The release() method must be called after the caller is finished
96          with the object and throw away the reference to it, e.g.
97          <PRE>
98              Page p = (Page) pageCache.findCached(pageKey);
99              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) throws StandardException;
173 
174     /**
175         Release a Cacheable object previously found with find() or findCached().
176         After this call the caller must throw away the reference to item.
177 
178     */
179     public void release(Cacheable entry);
180 
181     /**
182         Delete and remove an object from the cache. It is up to the user of the cache
183         to provide synchronization of some form that ensures that only one caller
184         executes remove() on a cached object.
185         <BR>
186         The object must have previously been found with find() or findCached().
187         The item will be placed into the NoIdentity
188         state through clean(true) (if required) and clearIdentity(). The removal of the
189         object will be delayed until it is not kept by anyone. Objects that are in the
190         to be removed state can still be found through find() and findCached()
191         until their keep count drops to zero. This call waits until the object
192         has been removed.
193         <BR>
194         After this call the caller must throw away the reference to item.
195 
196         @exception StandardException Standard Cloudscape error policy.
197     */
198     public void remove(Cacheable entry) throws StandardException;
199 
200     /**
201         Place all objects in their clean state by calling their clean method
202         if they are dirty. This method guarantees that all objects that existed
203         in the cache at the time of the call are placed in the clean state 
204         sometime during this call. Objects that are added to the cache during 
205         this call or objects that are dirtied during this call (by other 
206         callers) are not guaranteed to be clean once this call returns.
207 
208         @see Cacheable#clean
209         @see Cacheable#isDirty
210 
211         @exception StandardException Standard Cloudscape error policy.
212     */
213     public void cleanAll() throws StandardException;
214 
215     /**
216         Clean all objects that match the partialKey (or exact key).
217         Any cached object that results in the partialKey.equals(Object)
218         method returning true when passed the cached object will be cleaned. 
219         <P>
220         In order to clean more than one object the Cacheable equals method must
221         be able to handle a partial key, e.g. a page has PageKey but a clean 
222         may pass a ContainerKey which will discard all pages in that container.
223 
224         @exception StandardException Standard Cloudscape error policy.
225     */
226     public void clean(Matchable partialKey) throws StandardException;
227 
228     /**
229         Age as many objects as possible out of the cache.
230         This call is guaranteed not to block.
231         It is not guaranteed to leave the cache empty.
232 
233         <BR>
234         It is guaranteed that all unkept, clean objects will be
235         removed from the cache.
236 
237         @see Cacheable#clean
238         @see Cacheable#clearIdentity
239 
240 
241     */
242     public void ageOut();
243 
244     /**
245         Shutdown the cache. This call stops the cache returning
246         any more valid references on a find() or findCached() call,
247         and then cleanAll() and ageOut() are called. The cache remains
248         in existence until the last kept object has been unkept.
249 
250         @exception StandardException Standard Cloudscape error policy.
251 
252     */
253     public void shutdown() throws StandardException;
254 
255     /**
256         This cache can use this DaemonService if it needs some work to be done
257         int he background 
258     */
259     public void useDaemonService(DaemonService daemon);
260 
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 }
307
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags