001: package javax.cache;
002:
003: import java.util.Collection;
004: import java.util.Map;
005:
006: /**
007: * <p/>
008: * A cache, being a mechanism for efficient temporary storage of objects
009: * for the purpose of improving the overall performance of an application
010: * system, should not be necessary for the application to function correctly,
011: * it only improves the performance.
012: * <p/>
013: * A cache could be scoped, for examples to a JVM, all JVMs on a node, all
014: * nodes in a cluster, etc. Operations that are scoped to a cache such as put
015: * or load would affect all JVM�s in the cache. So the object loaded in 1 JVM
016: * would be equally available to all other JVMs in the cache.
017: * <p/>
018: * Objects are identified in the cache by a key. A key can be any Java
019: * object that implements the equals and hashcode methods. If the object is
020: * to be distributed or persisted (if supported) it must implement
021: * serializable.
022: * Each object in the cache will have a CacheEntry object associated with
023: * it. This object will encapsulate the metadata associated with the cached
024: * object. Mainly it represents the object statistics.
025: * "CacheStatistics" represents the read-only statistics of the cache,
026: * while "CacheAttributes" represents the user settable attributes of the
027: * cache.
028: * <p/>
029: * What now follows are explanations of the behavior of the standard Map
030: * methods:
031: * <p/>
032: * Returns true if the cache contains the specified key. The search is
033: * scoped to the cache. Other caches in the system will not be searched
034: * and a CacheLoader will not be called.
035: *
036: * @param key key whose presence in this cache is to be tested.
037: * @return true, if the cache contains the specified key.
038: * <p/>
039: * public boolean containsKey(Object key);
040: * <p/>
041: * <p/>
042: * Returns <tt>true</tt> if this cache maps one or more keys to the
043: * specified value. More formally, returns <tt>true</tt> if and only if
044: * this cache contains at least one mapping to a value <tt>v</tt> such that
045: * <tt>(value==null ? v==null : value.equals(v))</tt>.
046: * @param value value whose presence in this cache is to be tested.
047: * @return true if the cache contains one or more keys to the specified value.
048: * <p/>
049: * public boolean containsValue(Object value);
050: * <p/>
051: * // REVIEW talip: will the behavior stay unspecified?? Implementation can
052: * // mark the entry as removed so that iterator can skip it.
053: * <p/>
054: * Returns a set view of the objects currently contained in the cache.
055: * A CacheLoader will not be called. The behavior is unspecified for the
056: * case when an object is removed from the cache while the return set is
057: * being traversed.
058: * @return a set view of the mappings contained in this cache.
059: * <p/>
060: * public Set entrySet();
061: * <p/>
062: * <p/>
063: * Equality is based on the Set returned by entrySet. Equal will return
064: * true if the two objects are referencing the same object or
065: * entrySet.equals(((Map)o).entrySet()) returns true.
066: * <p/>
067: * <p/>
068: * public boolean equals(Object o);
069: * <p/>
070: * <p/>
071: * <p/>
072: * Returns the hash code value for this cache.
073: * @return the hash code value for this cache.
074: * <p/>
075: * public int hashCode();
076: * <p/>
077: * <p/>
078: * Return true if entrySet().isEmpty() return true.
079: * @return true if entrySet().isEmpty() returns true.
080: * <p/>
081: * public boolean isEmpty();
082: * <p/>
083: * <p/>
084: * Returns a set view of the keys currently contained in the cache. A
085: * CacheLoader will not be called. The behavior is unspecified for the
086: * case when an object is remove from the cache while the return set is
087: * being traversed.
088: * @return a set view of the keys in this cache
089: * <p/>
090: * public Set keySet();
091: * <p/>
092: * <p/>
093: * Copies all of the mappings from the specified map to the cache. This
094: * would be equivalent to t.entrySet() then iterating through the Set and
095: * calling put with each key value pair.
096: * @param t the map whose mappings to be copied to this cache.
097: * <p/>
098: * public void putAll(Map t);
099: * <p/>
100: * <p/>
101: * Returns the size of this map.
102: * @return the number of objects in the cache. This should be the same
103: * value as entrySet().size();
104: * <p/>
105: * public int size();
106: * <p/>
107: * <p/>
108: * Returns a collection view of the values contained in this cache.
109: * @return a collection view of the values contained in this cache.
110: * <p/>
111: * public Collection values();
112: * <p/>
113: * <p/>
114: * The get method will return, from the cache, the object associated with
115: * the argument "key". If the object is not in the cache, the associated
116: * cache loader will be called. If no loader is associated with the object,
117: * a null is returned. If a problem is encountered during the retrieving
118: * or loading of the object, an exception (to be defined) will be thrown.
119: * If the "arg" argument is set, the arg object will be passed to the
120: * CacheLoader.load method. The cache will not dereference the object.
121: * If no "arg" value is provided a null will be passed to the load method.
122: * The storing of null values in the cache is permitted, however, the get
123: * method will not distinguish returning a null stored in the cache and
124: * not finding the object in the cache. In both cases a null is returned.
125: * @param key key whose associated value is to be returned.
126: * @return the value to which this cache maps the specified key, or
127: * <tt>null</tt> if the cache contains no mapping for this key.
128: * <p/>
129: * public Object get(Object key);
130: * <p/>
131: * // REVIEW adam@bea.com 23-Jun-04 - I think that it is strange that get()
132: * // doesn't throw an exception whereas getAll() does. I understand the
133: * // historical reason for it, but think it looks ugly nonetheless.
134: * <p/>
135: * The put method adds the object "value" to the cache identified by the
136: * object "key".
137: * <p/>
138: * public Object put(Object key, Object value);
139: * <p/>
140: * The remove method will delete the object from the cache including the
141: * key, the associated value and the associated CacheStatistics object.
142: * <p/>
143: * public Object remove(Object key);
144: * <p/>
145: * /**
146: * The clear method will remove all objects from the cache including the
147: * key, the associated value and the associated CacheStatistics object.
148: * <p/>
149: * public void clear();
150: */
151: public interface Cache<K, V> extends Map<K, V> // @@@ Should be ConcurrentMap, NYI
152: {
153:
154: enum State {
155: STARTING, RUNNING, STOPPING, TERMINATED
156: }
157:
158: /**
159: * The getAll method will return, from the cache, a Map of the objects
160: * associated with the Collection of keys in argument "keys". If the objects
161: * are not in the cache, the associated cache loader will be called. If no
162: * loader is associated with an object, a null is returned. If a problem
163: * is encountered during the retrieving or loading of the objects, an
164: * exception will be thrown.
165: * If the "arg" argument is set, the arg object will be passed to the
166: * CacheLoader.loadAll method. The cache will not dereference the object.
167: * If no "arg" value is provided a null will be passed to the loadAll
168: * method.
169: * The storing of null values in the cache is permitted, however, the get
170: * method will not distinguish returning a null stored in the cache and
171: * not finding the object in the cache. In both cases a null is returned.
172: */
173: Map<K, V> getAll(Collection<? extends K> keys)
174: throws CacheException;
175:
176: /**
177: * The load method provides a means to "pre load" the cache. This method
178: * will, asynchronously, load the specified object into the cache using
179: * the associated cacheloader. If the object already exists in the cache,
180: * no action is taken. If no loader is associated with the object, no object
181: * will be loaded into the cache. If a problem is encountered during the
182: * retrieving or loading of the object, an exception should
183: * be logged.
184: * If the "arg" argument is set, the arg object will be passed to the
185: * CacheLoader.load method. The cache will not dereference the object. If
186: * no "arg" value is provided a null will be passed to the load method.
187: * The storing of null values in the cache is permitted, however, the get
188: * method will not distinguish returning a null stored in the cache and not
189: * finding the object in the cache. In both cases a null is returned.
190: *
191: * @param key key whose associated value to be loaded using the
192: * associated cacheloader if this cache doesn't contain it.
193: * @throws CacheException //REVIEW when??? is this a wrapper exception for the
194: * the exceptions occured during the loading?
195: */
196: void load(K key) throws CacheException;
197:
198: /**
199: * The loadAll method provides a means to "pre load" objects into the cache.
200: * This method will, asynchronously, load the specified objects into the
201: * cache using the associated cache loader. If the an object already exists
202: * in the cache, no action is taken. If no loader is associated with the
203: * object, no object will be loaded into the cache. If a problem is
204: * encountered during the retrieving or loading of the objects, an
205: * exception (to be defined) should be logged.
206: * The getAll method will return, from the cache, a Map of the objects
207: * associated with the Collection of keys in argument "keys". If the objects
208: * are not in the cache, the associated cache loader will be called. If no
209: * loader is associated with an object, a null is returned. If a problem
210: * is encountered during the retrieving or loading of the objects, an
211: * exception (to be defined) will be thrown.
212: * If the "arg" argument is set, the arg object will be passed to the
213: * CacheLoader.loadAll method. The cache will not dereference the object.
214: * If no "arg" value is provided a null will be passed to the loadAll
215: * method.
216: *
217: * @param keys collection of the keys whose associated values to be loaded into
218: * this cache by using the associated cacheloader if this cache doesn't contain
219: * them.
220: * @throws CacheException //REVIEW when??? is this a wrapper exception for the
221: * the exceptions occured during the loading?
222: */
223: void loadAll(Collection<? extends K> keys) throws CacheException;
224:
225: /**
226: * The peek method will return the object associated with "key" if it
227: * currently exists (and is valid) in the cache. If not, a null is
228: * returned. With "peek" the CacheLoader will not be invoked and other
229: * caches in the system will not be searched.
230: *
231: * @param key key whose associated value is to be peeked.
232: */
233: V peek(K key);
234:
235: /**
236: * Returns the CacheEntry object associated with the object identified by
237: * "key". If the object is not in the cache, or the object is expired,
238: * a null is returned.
239: */
240: CacheEntry<K, V> getCacheEntry(K key);
241:
242: /**
243: * Returns the CacheStatistics object associated with the cache.
244: * May return null if the cache does not support statistics gathering.
245: */
246: CacheStatistics getStatistics();
247:
248: /**
249: * /**
250: * The evict method will remove objects from the cache that are no longer
251: * valid. Objects where the specified expiration time has been reached.
252: */
253: void evict();
254:
255: /**
256: * Add a listener to the list of cache listeners
257: */
258: void addListener(CacheListener<K, V> listener);
259:
260: /**
261: * Remove a listener from the list of cache listeners
262: */
263: void removeListener(CacheListener<K, V> listener);
264:
265: State getState();
266:
267: String getName();
268:
269: V put(K key, V value, long timeToLive);
270:
271: void shutdown();
272:
273: void clearStatistics();
274:
275: CacheStatistics getCacheStatistics();
276:
277: /**
278: * All caches belong to a CacheManager
279: * @return the CacheManager for this Cache
280: */
281: CacheManager getCacheManager();
282:
283: // REVIEW BG: This should not be called from user code, only from a CacheManager. Should probably not be in the API, but the SPI
284: void setCacheManager(CacheManager cacheManager);
285:
286: }
|