001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/memory/tags/sakai_2-4-1/memory-api/api/src/java/org/sakaiproject/memory/api/Cache.java $
003: * $Id: Cache.java 12712 2006-07-24 04:09:14Z ggolden@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
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: **********************************************************************************/package org.sakaiproject.memory.api;
021:
022: import java.util.List;
023:
024: /**
025: * <p>
026: * A Cache holds objects with keys with a limited lifespan.
027: * </p>
028: * <p>
029: * When the object expires, the cache may call upon a CacheRefresher to update the key's value. The update is done in a separate thread.
030: * </p>
031: */
032: public interface Cache extends Cacher {
033: /**
034: * Cache an object
035: *
036: * @param key
037: * The key with which to find the object.
038: * @param payload
039: * The object to cache.
040: * @param duration
041: * The time to cache the object (seconds).
042: */
043: void put(Object key, Object payload, int duration);
044:
045: /**
046: * Cache an object - don't automatically exipire it.
047: *
048: * @param key
049: * The key with which to find the object.
050: * @param payload
051: * The object to cache.
052: * @param duration
053: * The time to cache the object (seconds).
054: */
055: void put(Object key, Object payload);
056:
057: /**
058: * Test for an entry in the cache - expired or not.
059: *
060: * @param key
061: * The cache key.
062: * @return true if the key maps to a cache entry, false if not.
063: */
064: boolean containsKeyExpiredOrNot(Object key);
065:
066: /**
067: * Test for a non expired entry in the cache.
068: *
069: * @param key
070: * The cache key.
071: * @return true if the key maps to a non-expired cache entry, false if not.
072: */
073: boolean containsKey(Object key);
074:
075: /**
076: * Expire this object.
077: *
078: * @param key
079: * The cache key.
080: */
081: void expire(Object key);
082:
083: /**
084: * Get the entry, or null if not there (expired entries are returned, too).
085: *
086: * @param key
087: * The cache key.
088: * @return The payload, or null if the payload is null, the key is not found. (Note: use containsKey() to remove this ambiguity).
089: */
090: Object getExpiredOrNot(Object key);
091:
092: /**
093: * Get the non expired entry, or null if not there (or expired)
094: *
095: * @param key
096: * The cache key.
097: * @return The payload, or null if the payload is null, the key is not found, or the entry has expired (Note: use containsKey() to remove this ambiguity).
098: */
099: Object get(Object key);
100:
101: /**
102: * Get all the non-expired non-null entries.
103: *
104: * @return all the non-expired non-null entries, or an empty list if none.
105: */
106: List getAll();
107:
108: /**
109: * Get all the non-expired non-null entries that are in the specified reference path. Note: only works with String keys.
110: *
111: * @param path
112: * The reference path.
113: * @return all the non-expired non-null entries, or an empty list if none.
114: */
115: List getAll(String path);
116:
117: /**
118: * Get all the keys
119: *
120: * @return The List of key values (Object).
121: */
122: List getKeys();
123:
124: /**
125: * Get all the keys, modified from resource references to ids by removing the resource prefix. Note: only works with String keys.
126: *
127: * @return The List of keys converted from references to ids (String).
128: */
129: List getIds();
130:
131: /**
132: * Clear all entries.
133: */
134: void clear();
135:
136: /**
137: * Remove this entry from the cache.
138: *
139: * @param key
140: * The cache key.
141: */
142: void remove(Object key);
143:
144: /**
145: * Disable the cache.
146: */
147: void disable();
148:
149: /**
150: * Enable the cache.
151: */
152: void enable();
153:
154: /**
155: * Is the cache disabled?
156: *
157: * @return true if the cache is disabled, false if it is enabled.
158: */
159: boolean disabled();
160:
161: /**
162: * Are we complete?
163: *
164: * @return true if we have all the possible entries cached, false if not.
165: */
166: boolean isComplete();
167:
168: /**
169: * Set the cache to be complete, containing all possible entries.
170: */
171: void setComplete();
172:
173: /**
174: * Are we complete for one level of the reference hierarchy?
175: *
176: * @param path
177: * The reference to the completion level.
178: * @return true if we have all the possible entries cached, false if not.
179: */
180: boolean isComplete(String path);
181:
182: /**
183: * Set the cache to be complete for one level of the reference hierarchy.
184: *
185: * @param path
186: * The reference to the completion level.
187: */
188: void setComplete(String path);
189:
190: /**
191: * Set the cache to hold events for later processing to assure an atomic "complete" load.
192: */
193: void holdEvents();
194:
195: /**
196: * Restore normal event processing in the cache, and process any held events now.
197: */
198: void processEvents();
199:
200: /**
201: * Clear all entries and shudown the cache. Don't use after this call.
202: */
203: void destroy();
204:
205: /**
206: * Attach this DerivedCache to the cache. The DerivedCache is then notified of the cache contents changing events.
207: *
208: * @param cache
209: * The DerivedCache to attach.
210: */
211: void attachDerivedCache(DerivedCache cache);
212: }
|