CacheSystem


1   /* ====================================================================
2    * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002
3    *
4    * Copyright (c) 1995-2002 Jcorporate Ltd. All rights reserved.
5    *
6    * Redistribution and use in source and binary forms, with or without
7    * modification, are permitted provided that the following conditions
8    * are met:
9    *
10   * 1. Redistributions of source code must retain the above copyright
11   *    notice, this list of conditions and the following disclaimer.
12   *
13   * 2. Redistributions in binary form must reproduce the above copyright
14   *    notice, this list of conditions and the following disclaimer in
15   *    the documentation and/or other materials provided with the
16   *    distribution.
17   *
18   * 3. The end-user documentation included with the redistribution,
19   *    if any, must include the following acknowledgment:
20   *       "This product includes software developed by Jcorporate Ltd.
21   *        (http://www.jcorporate.com/)."
22   *    Alternately, this acknowledgment may appear in the software itself,
23   *    if and wherever such third-party acknowledgments normally appear.
24   *
25   * 4. "Jcorporate" and product names such as "Expresso" must
26   *    not be used to endorse or promote products derived from this
27   *    software without prior written permission. For written permission,
28   *    please contact info@jcorporate.com.
29   *
30   * 5. Products derived from this software may not be called "Expresso",
31   *    or other Jcorporate product names; nor may "Expresso" or other
32   *    Jcorporate product names appear in their name, without prior
33   *    written permission of Jcorporate Ltd.
34   *
35   * 6. No product derived from this software may compete in the same
36   *    market space, i.e. framework, without prior written permission
37   *    of Jcorporate Ltd. For written permission, please contact
38   *    partners@jcorporate.com.
39   *
40   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
41   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
42   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
43   * DISCLAIMED.  IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS
44   * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
45   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
46   * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
47   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
48   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
49   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
50   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51   * SUCH DAMAGE.
52   * ====================================================================
53   *
54   * This software consists of voluntary contributions made by many
55   * individuals on behalf of the Jcorporate Ltd. Contributions back
56   * to the project(s) are encouraged when you make modifications.
57   * Please send them to support@jcorporate.com. For more information
58   * on Jcorporate Ltd. and its products, please see
59   * <http://www.jcorporate.com/>.
60   *
61   * Portions of this software are based upon other open source
62   * products and are subject to their respective licenses.
63   */
64  
65  package com.jcorporate.expresso.core.cache;
66  
67  /**
68   * This is an interface for an underlying cache system.  It allows clients
69   * of the itnerface to add items, retrieve items, and clear caches.
70   * <p/>
71   * The CacheSystem is not data context aware.  Classes that implement this
72   * interface are expected to be one instance per context.  The Component System
73   * provides differentiation between caches.
74   * </p>
75   *
76   * @author Michael Rimov
77   * @since Expresso 5.1
78   */
79  public interface CacheSystem {
80  
81      /**
82       * Instructs the cache system to adjust it's usage profile based upon
83       * current memory information that the expresso system is telling us.
84       */
85      void adjustForMemory();
86  
87      /**
88       * Return an iterator over a list of Strings that contain all the names of
89       * the caches stored in the system [For dbContext default]
90       *
91       * @return java.util.Iterator
92       */
93      java.util.Set   getAllCacheNames();
94  
95      /**
96       * Get a particular item in the cache
97       *
98       * @param cacheName The name of the cache
99       * @param valueKey  The particular item within the cache to get
100      * @return a Cacheable object or null if it doesn't exist in the cache
101      */
102     Cacheable getItem(String   cacheName, String   valueKey);
103 
104 
105     /**
106      * Retrieve a given cache by name.
107      *
108      * @param cacheName the name of the cache to retrieve.
109      * @return a Cache instance or null if the Cache does not exist.
110      * @see com.jcorporate.expresso.core.cache.Cache
111      */
112     Cache getCache(String   cacheName);
113 
114     /**
115      * Return a count of the number of items in a cache. Return 0 if there is
116      * no such item
117      *
118      * @param cacheName The name of the cache
119      * @return an item count or zero if the cache doesn't exist or is empty;
120      */
121     int getItemCount(String   cacheName);
122 
123     /**
124      * Sets a cache to have the particular items specified in itemList.
125      *
126      * @param cacheName The name of the cache
127      * @param itemList  The items to set into the cache
128      * @throws CacheException if there's an error setting the items.
129      */
130     void setItems(String   cacheName, java.util.List   itemList) throws CacheException;
131 
132 
133     /**
134      * Sets a cache to have the particular items specified in itemList.
135      *
136      * @param cacheName  The name of the cache
137      * @param itemList   The items to set into the cache
138      * @param expiration the expiration time in milliseconds for the items.
139      * @throws CacheException if there's an error setting the items.
140      */
141     void setItems(String   cacheName, java.util.List   itemList, long expiration) throws CacheException;
142 
143     /**
144      * Return all of the items in a cache. If the cache was created as an
145      * ordered cache, the items will be in the order they were added. If not,
146      * they will be in no particular order. If there is no such cache or no
147      * items, null will be returned.
148      *
149      * @param cacheName The name of the cache to retrieve
150      * @return java.util.List of Cacheable items
151      */
152     java.util.List   getItems(String   cacheName);
153 
154     /**
155      * Adds a <code>Cacheable</code> item into the cache
156      *
157      * @param cacheName The name of the cache.
158      * @param newItem   The new item to add to the cache
159      * @throws CacheException upon error inserting into the system
160      */
161     void addItem(String   cacheName, Cacheable newItem) throws CacheException;
162 
163 
164     /**
165      * Adds an item to the cache named by parameter cacheName
166      *
167      * @param cacheName The name of the cache to store the object in
168      * @param newItem   The new item to add to the cache
169      * @param expiry    The time in miliseconds that this cache item will expire
170      * @throws CacheException if there's an error inserting the item into the
171      *                        cache
172      */
173     void addItem(String   cacheName, Cacheable newItem, long expiry) throws CacheException;
174 
175     /**
176      * Adds a <code>Cacheable</code> item into the cache <em>without</em> clearing
177      * related caches.  This is to differentiate between 'changed' items that
178      * are added to the cache via <code>addItem</code> that would require related
179      * caches to be cleared to maintain data integrity.  An example of when this
180      * is used is when <code>DBObject.retrieve()</code> is first called, there
181      * is no &quot;referential integrity&quot; issues because the object is
182      * fresh and unmodified.
183      *
184      * @param cacheName the name of the cache to add to
185      * @param newItem   the item to add
186      * @throws CacheException upon error putting the item into the cache
187      */
188     void put(String   cacheName, Cacheable newItem) throws CacheException;
189 
190     /**
191      * Adds a <code>Cacheable</code> item into the cache <em>without</em> clearing
192      * related caches.  This is to differentiate between 'changed' items that
193      * are added to the cache via <code>addItem</code> that would require related
194      * caches to be cleared to maintain data integrity. An example of when this
195      * is used is when <code>DBObject.retrieve()</code> is first called, there
196      * is no &quot;referential integrity&quot; issues because the object is
197      * fresh and unmodified.
198      *
199      * @param cacheName the name of the cache to add to
200      * @param newItem   the item to add
201      * @param expiry    The time in miliseconds that this cache item will expire
202      * @throws CacheException upon error putting the item into the cache
203      */
204     void put(String   cacheName, Cacheable newItem, long expiry) throws CacheException;
205 
206 
207     /**
208      * Specify a relationship between caches. Whenever an add, clear or remove
209      * event is sent to the specified cache, the listener is cleared as well.
210      * Adding a listener implies the relationship between the caches for the
211      * current
212      * db context.
213      *
214      * @param listener The classname of the listener
215      * @param listenTo The name of the cache to listen to.
216      */
217     void addListener(String   listener, String   listenTo);
218 
219     /**
220      * Clear's the named cache.
221      *
222      * @param cacheName The name of the cache to clear
223      * @throws CacheException if there's an error clearing the cache.
224      */
225     void clear(String   cacheName) throws CacheException;
226 
227     /**
228      * Removes all cache items for a particular data context
229      *
230      * @throws CacheException CacheException if there's an error clearing the
231      *                        cache
232      */
233     void clear() throws CacheException;
234 
235     /**
236      * Clears all caches in this db context but doesn't notify any listeners
237      */
238     void clearNoNotify();
239 
240     /**
241      * Clear the named cache, but don't send the remote system notifications.
242      * This method actually removes the cache from the list of available
243      * caches
244      *
245      * @param cacheName The name of the cache
246      */
247     void clearNoNotify(String   cacheName);
248 
249     /**
250      * Creates a cache as specified by the parameters listed. Creation date:
251      * (9/7/00 2:18:09 PM)
252      *
253      * @param cacheName java.lang.String the name of the cache
254      * @param ordered   boolean true if you want an ordered cache such as for
255      *                  ValidValues
256      * @return the newly instantiated Cache
257      */
258     Cache createCache(String   cacheName, boolean ordered) throws CacheException;
259 
260     /**
261      * Creates a cache defined by whether the cache is to be ordered, it's name
262      * and it's maximum size. Creation date: (9/7/00 2:18:09 PM)
263      *
264      * @param cacheName java.lang.String The name of the cache
265      * @param ordered   boolean True if you wish for an ordered cache.
266      * @param maxSize   The maximum size of the cache
267      * @return the newly instantiated cache
268      */
269     Cache createCache(String   cacheName, boolean ordered, int maxSize) throws CacheException;
270 
271     /**
272      * Checks to see if the cache already exists.  One big note about this is
273      * that unless you already have a ReadLock, the cache may or may not exist
274      * once you go to put your data in the cache.  Buyer beware.
275      *
276      * @param cacheName The name of the cache
277      * @return true if the named cache already exists in this data context
278      */
279     boolean existsCache(String   cacheName);
280 
281     /**
282      * Removes an item from the cache
283      *
284      * @param cacheName    The name of the cache
285      * @param itemToRemove the key of the item to remove
286      */
287     void removeItem(String   cacheName, Cacheable itemToRemove) throws CacheException;
288 
289     /**
290      * Removes an item out of the cache without notifying the cache listeners
291      *
292      * @param cacheName    The cache name
293      * @param itemToRemove the key in the cache that has been modified
294      * @throws CacheException Upon error removing the item from the cache
295      */
296     void removeItemNoNotify(String   cacheName, Cacheable itemToRemove) throws CacheException;
297 
298 
299     /**
300      * Displays the cache status.  Currently this is only really used for
301      * debugging purposes.
302      * Creation date: (9/7/00 2:44:05 PM)
303      */
304     void displayStatus();
305 
306 }
307
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags