001: /* ====================================================================
002: * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002
003: *
004: * Copyright (c) 1995-2002 Jcorporate Ltd. All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions
008: * are met:
009: *
010: * 1. Redistributions of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: *
013: * 2. Redistributions in binary form must reproduce the above copyright
014: * notice, this list of conditions and the following disclaimer in
015: * the documentation and/or other materials provided with the
016: * distribution.
017: *
018: * 3. The end-user documentation included with the redistribution,
019: * if any, must include the following acknowledgment:
020: * "This product includes software developed by Jcorporate Ltd.
021: * (http://www.jcorporate.com/)."
022: * Alternately, this acknowledgment may appear in the software itself,
023: * if and wherever such third-party acknowledgments normally appear.
024: *
025: * 4. "Jcorporate" and product names such as "Expresso" must
026: * not be used to endorse or promote products derived from this
027: * software without prior written permission. For written permission,
028: * please contact info@jcorporate.com.
029: *
030: * 5. Products derived from this software may not be called "Expresso",
031: * or other Jcorporate product names; nor may "Expresso" or other
032: * Jcorporate product names appear in their name, without prior
033: * written permission of Jcorporate Ltd.
034: *
035: * 6. No product derived from this software may compete in the same
036: * market space, i.e. framework, without prior written permission
037: * of Jcorporate Ltd. For written permission, please contact
038: * partners@jcorporate.com.
039: *
040: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
041: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
042: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
043: * DISCLAIMED. IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS
044: * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
045: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
046: * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
047: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
048: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
049: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
050: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
051: * SUCH DAMAGE.
052: * ====================================================================
053: *
054: * This software consists of voluntary contributions made by many
055: * individuals on behalf of the Jcorporate Ltd. Contributions back
056: * to the project(s) are encouraged when you make modifications.
057: * Please send them to support@jcorporate.com. For more information
058: * on Jcorporate Ltd. and its products, please see
059: * <http://www.jcorporate.com/>.
060: *
061: * Portions of this software are based upon other open source
062: * products and are subject to their respective licenses.
063: */
064:
065: package com.jcorporate.expresso.core.cache;
066:
067: /**
068: * This is an interface for an underlying cache system. It allows clients
069: * of the itnerface to add items, retrieve items, and clear caches.
070: * <p/>
071: * The CacheSystem is not data context aware. Classes that implement this
072: * interface are expected to be one instance per context. The Component System
073: * provides differentiation between caches.
074: * </p>
075: *
076: * @author Michael Rimov
077: * @since Expresso 5.1
078: */
079: public interface CacheSystem {
080:
081: /**
082: * Instructs the cache system to adjust it's usage profile based upon
083: * current memory information that the expresso system is telling us.
084: */
085: void adjustForMemory();
086:
087: /**
088: * Return an iterator over a list of Strings that contain all the names of
089: * the caches stored in the system [For dbContext default]
090: *
091: * @return java.util.Iterator
092: */
093: java.util.Set getAllCacheNames();
094:
095: /**
096: * Get a particular item in the cache
097: *
098: * @param cacheName The name of the cache
099: * @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: * Retrieve a given cache by name.
106: *
107: * @param cacheName the name of the cache to retrieve.
108: * @return a Cache instance or null if the Cache does not exist.
109: * @see com.jcorporate.expresso.core.cache.Cache
110: */
111: Cache getCache(String cacheName);
112:
113: /**
114: * Return a count of the number of items in a cache. Return 0 if there is
115: * no such item
116: *
117: * @param cacheName The name of the cache
118: * @return an item count or zero if the cache doesn't exist or is empty;
119: */
120: int getItemCount(String cacheName);
121:
122: /**
123: * Sets a cache to have the particular items specified in itemList.
124: *
125: * @param cacheName The name of the cache
126: * @param itemList The items to set into the cache
127: * @throws CacheException if there's an error setting the items.
128: */
129: void setItems(String cacheName, java.util.List itemList)
130: throws CacheException;
131:
132: /**
133: * Sets a cache to have the particular items specified in itemList.
134: *
135: * @param cacheName The name of the cache
136: * @param itemList The items to set into the cache
137: * @param expiration the expiration time in milliseconds for the items.
138: * @throws CacheException if there's an error setting the items.
139: */
140: void setItems(String cacheName, java.util.List itemList,
141: 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)
162: throws CacheException;
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)
174: throws CacheException;
175:
176: /**
177: * Adds a <code>Cacheable</code> item into the cache <em>without</em> clearing
178: * related caches. This is to differentiate between 'changed' items that
179: * are added to the cache via <code>addItem</code> that would require related
180: * caches to be cleared to maintain data integrity. An example of when this
181: * is used is when <code>DBObject.retrieve()</code> is first called, there
182: * is no "referential integrity" issues because the object is
183: * fresh and unmodified.
184: *
185: * @param cacheName the name of the cache to add to
186: * @param newItem the item to add
187: * @throws CacheException upon error putting the item into the cache
188: */
189: void put(String cacheName, Cacheable newItem) throws CacheException;
190:
191: /**
192: * Adds a <code>Cacheable</code> item into the cache <em>without</em> clearing
193: * related caches. This is to differentiate between 'changed' items that
194: * are added to the cache via <code>addItem</code> that would require related
195: * caches to be cleared to maintain data integrity. An example of when this
196: * is used is when <code>DBObject.retrieve()</code> is first called, there
197: * is no "referential integrity" issues because the object is
198: * fresh and unmodified.
199: *
200: * @param cacheName the name of the cache to add to
201: * @param newItem the item to add
202: * @param expiry The time in miliseconds that this cache item will expire
203: * @throws CacheException upon error putting the item into the cache
204: */
205: void put(String cacheName, Cacheable newItem, long expiry)
206: throws CacheException;
207:
208: /**
209: * Specify a relationship between caches. Whenever an add, clear or remove
210: * event is sent to the specified cache, the listener is cleared as well.
211: * Adding a listener implies the relationship between the caches for the
212: * current
213: * db context.
214: *
215: * @param listener The classname of the listener
216: * @param listenTo The name of the cache to listen to.
217: */
218: void addListener(String listener, String listenTo);
219:
220: /**
221: * Clear's the named cache.
222: *
223: * @param cacheName The name of the cache to clear
224: * @throws CacheException if there's an error clearing the cache.
225: */
226: void clear(String cacheName) throws CacheException;
227:
228: /**
229: * Removes all cache items for a particular data context
230: *
231: * @throws CacheException CacheException if there's an error clearing the
232: * cache
233: */
234: void clear() throws CacheException;
235:
236: /**
237: * Clears all caches in this db context but doesn't notify any listeners
238: */
239: void clearNoNotify();
240:
241: /**
242: * Clear the named cache, but don't send the remote system notifications.
243: * This method actually removes the cache from the list of available
244: * caches
245: *
246: * @param cacheName The name of the cache
247: */
248: void clearNoNotify(String cacheName);
249:
250: /**
251: * Creates a cache as specified by the parameters listed. Creation date:
252: * (9/7/00 2:18:09 PM)
253: *
254: * @param cacheName java.lang.String the name of the cache
255: * @param ordered boolean true if you want an ordered cache such as for
256: * ValidValues
257: * @return the newly instantiated Cache
258: */
259: Cache createCache(String cacheName, boolean ordered)
260: throws CacheException;
261:
262: /**
263: * Creates a cache defined by whether the cache is to be ordered, it's name
264: * and it's maximum size. Creation date: (9/7/00 2:18:09 PM)
265: *
266: * @param cacheName java.lang.String The name of the cache
267: * @param ordered boolean True if you wish for an ordered cache.
268: * @param maxSize The maximum size of the cache
269: * @return the newly instantiated cache
270: */
271: Cache createCache(String cacheName, boolean ordered, int maxSize)
272: throws CacheException;
273:
274: /**
275: * Checks to see if the cache already exists. One big note about this is
276: * that unless you already have a ReadLock, the cache may or may not exist
277: * once you go to put your data in the cache. Buyer beware.
278: *
279: * @param cacheName The name of the cache
280: * @return true if the named cache already exists in this data context
281: */
282: boolean existsCache(String cacheName);
283:
284: /**
285: * Removes an item from the cache
286: *
287: * @param cacheName The name of the cache
288: * @param itemToRemove the key of the item to remove
289: */
290: void removeItem(String cacheName, Cacheable itemToRemove)
291: throws CacheException;
292:
293: /**
294: * Removes an item out of the cache without notifying the cache listeners
295: *
296: * @param cacheName The cache name
297: * @param itemToRemove the key in the cache that has been modified
298: * @throws CacheException Upon error removing the item from the cache
299: */
300: void removeItemNoNotify(String cacheName, Cacheable itemToRemove)
301: throws CacheException;
302:
303: /**
304: * Displays the cache status. Currently this is only really used for
305: * debugging purposes.
306: * Creation date: (9/7/00 2:44:05 PM)
307: */
308: void displayStatus();
309:
310: }
|