Java Doc for Cache.java in  » 6.0-JDK-Modules » jsr107 » javax » cache » Java Source Code / Java DocumentationJava Source Code and Java Documentation

A cache, being a mechanism for efficient temporary storage of objects for the purpose of improving the overall performance of an application system, should not be necessary for the application to function correctly, it only improves the performance.

A cache could be scoped, for examples to a JVM, all JVMs on a node, all nodes in a cluster, etc. Operations that are scoped to a cache such as put or load would affect all JVM�s in the cache. So the object loaded in 1 JVM would be equally available to all other JVMs in the cache.

Objects are identified in the cache by a key. A key can be any Java object that implements the equals and hashcode methods. If the object is to be distributed or persisted (if supported) it must implement serializable. Each object in the cache will have a CacheEntry object associated with it. This object will encapsulate the metadata associated with the cached object. Mainly it represents the object statistics. "CacheStatistics" represents the read-only statistics of the cache, while "CacheAttributes" represents the user settable attributes of the cache.

What now follows are explanations of the behavior of the standard Map methods:

Returns true if the cache contains the specified key. The search is scoped to the cache. Other caches in the system will not be searched and a CacheLoader will not be called.
Parameters:
  key - key whose presence in this cache is to be tested. true, if the cache contains the specified key.

public boolean containsKey(Object key);

Returns true if this cache maps one or more keys to thespecified value. More formally, returns true if and only ifthis cache contains at least one mapping to a value v such that(value==null ? v==null : value.equals(v)).
Parameters:
  value - value whose presence in this cache is to be tested. true if the cache contains one or more keys to the specified value.

public boolean containsValue(Object value);

// REVIEW talip: will the behavior stay unspecified?? Implementation can// mark the entry as removed so that iterator can skip it.

Returns a set view of the objects currently contained in the cache.A CacheLoader will not be called. The behavior is unspecified for thecase when an object is removed from the cache while the return set isbeing traversed. a set view of the mappings contained in this cache.

public Set entrySet();

Equality is based on the Set returned by entrySet. Equal will returntrue if the two objects are referencing the same object orentrySet.equals(((Map)o).entrySet()) returns true.

public boolean equals(Object o);

Returns the hash code value for this cache. the hash code value for this cache.

public int hashCode();

Return true if entrySet().isEmpty() return true. true if entrySet().isEmpty() returns true.

public boolean isEmpty();

Returns a set view of the keys currently contained in the cache. ACacheLoader will not be called. The behavior is unspecified for thecase when an object is remove from the cache while the return set isbeing traversed. a set view of the keys in this cache

public Set keySet();

Copies all of the mappings from the specified map to the cache. Thiswould be equivalent to t.entrySet() then iterating through the Set andcalling put with each key value pair.
Parameters:
  t - the map whose mappings to be copied to this cache.

public void putAll(Map t);

Returns the size of this map. the number of objects in the cache. This should be the samevalue as entrySet().size();

public int size();

Returns a collection view of the values contained in this cache. a collection view of the values contained in this cache.

public Collection values();

The get method will return, from the cache, the object associated withthe argument "key". If the object is not in the cache, the associatedcache loader will be called. If no loader is associated with the object,a null is returned. If a problem is encountered during the retrievingor loading of the object, an exception (to be defined) will be thrown.If the "arg" argument is set, the arg object will be passed to theCacheLoader.load method. The cache will not dereference the object.If no "arg" value is provided a null will be passed to the load method.The storing of null values in the cache is permitted, however, the getmethod will not distinguish returning a null stored in the cache andnot finding the object in the cache. In both cases a null is returned.
Parameters:
  key - key whose associated value is to be returned. the value to which this cache maps the specified key, ornull if the cache contains no mapping for this key.

public Object get(Object key);

// REVIEW adam@bea.com 23-Jun-04 - I think that it is strange that get()// doesn't throw an exception whereas getAll() does. I understand the// historical reason for it, but think it looks ugly nonetheless.

The put method adds the object "value" to the cache identified by theobject "key".

public Object put(Object key, Object value);

The remove method will delete the object from the cache including thekey, the associated value and the associated CacheStatistics object.

public Object remove(Object key);

/**The clear method will remove all objects from the cache including thekey, the associated value and the associated CacheStatistics object.

public void clear();