ehcache

net.sf.jsr107cache
Interface Cache

All Superinterfaces:
Map

public interface Cache
extends Map

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 JVMs 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.


Nested Class Summary
 
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
 
Method Summary
 void addListener(CacheListener listener)
          Add a listener to the list of cache listeners
 void clear()
          The clear method will remove all objects from the cache including the key, the associated value and the associated CacheStatistics object.
 boolean containsKey(Object key)
          Returns true if the cache contains the specified key.
 boolean containsValue(Object value)
           
 Set entrySet()
          Returns a set view of the objects currently contained in the cache.
 boolean equals(Object o)
          Equality is based on the Set returned by entrySet.
 void evict()
          The evict method will remove objects from the cache that are no longer valid.
 Object get(Object key)
          The get method will return, from the cache, the object associated with the argument "key".
 Map getAll(Collection keys)
          The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys".
 CacheEntry getCacheEntry(Object key)
          Returns the CacheEntry object associated with the object identified by "key".
 CacheStatistics getCacheStatistics()
          Returns the CacheStatistics object associated with the cache.
 int hashCode()
           
 boolean isEmpty()
           
 Set keySet()
          Returns a set view of the keys currently contained in the cache.
 void load(Object key)
          The load method provides a means to "pre load" the cache.
 void loadAll(Collection keys)
          The loadAll method provides a means to "pre load" objects into the cache.
 Object peek(Object key)
          The peek method will return the object associated with "key" if it currently exists (and is valid) in the cache.
 Object put(Object key, Object value)
          The put method adds the object "value" to the cache identified by the object "key".
 void putAll(Map t)
          Copies all of the mappings from the specified map to the cache.
 Object remove(Object key)
          The remove method will delete the object from the cache including the key, the associated value and the associated CacheStatistics object.
 void removeListener(CacheListener listener)
          Remove a listener from the list of cache listeners
 int size()
           
 Collection values()
           
 

Method Detail

containsKey

boolean containsKey(Object key)
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.

Specified by:
containsKey in interface Map
Returns:
true, if the cache contains the specified key.

containsValue

boolean containsValue(Object value)
Specified by:
containsValue in interface Map
Returns:
true if the cache contains one or more keys to the specified value.

entrySet

Set entrySet()
Returns a set view of the objects currently contained in the cache. A CacheLoader will not be called. The behavior is unspecified for the case when an object is remove from the cache while the return set is being traversed.

Specified by:
entrySet in interface Map

equals

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

Specified by:
equals in interface Map
Overrides:
equals in class Object

hashCode

int hashCode()
Specified by:
hashCode in interface Map
Overrides:
hashCode in class Object
Returns:
the hash code value for this the cache.

isEmpty

boolean isEmpty()
Specified by:
isEmpty in interface Map
Returns:
true if entrySet().isEmpty() returns true.

keySet

Set keySet()
Returns a set view of the keys currently contained in the cache. A CacheLoader will not be called. The behavior is unspecified for the case when an object is remove from the cache while the return set is being traversed.

Specified by:
keySet in interface Map

putAll

void putAll(Map t)
Copies all of the mappings from the specified map to the cache. This would be equivalent to t.entrySet() then iterating through the Set and calling put with each key value pair.

Specified by:
putAll in interface Map

size

int size()
Specified by:
size in interface Map
Returns:
the number of objects in the cache. This should be the same value as entrySet().size();

values

Collection values()
Specified by:
values in interface Map
Returns:
a collection view of the values contained in the cache.

get

Object get(Object key)
The get method will return, from the cache, the object associated with the argument "key". If the object is not in the cache, the associated cache loader will be called. If no loader is associated with the object, a null is returned. If a problem is encountered during the retrieving or 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 the CacheLoader.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 get method will not distinguish returning a null stored in the cache and not finding the object in the cache. In both cases a null is returned.

Specified by:
get in interface Map

getAll

Map getAll(Collection keys)
           throws CacheException
The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys". If the objects are not in the cache, the associated cache loader will be called. If no loader is associated with an object, a null is returned. If a problem is encountered during the retrieving or loading of the objects, an exception will be thrown. If the "arg" argument is set, the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the loadAll method. The storing of null values in the cache is permitted, however, the get method will not distinguish returning a null stored in the cache and not finding the object in the cache. In both cases a null is returned.

Throws:
CacheException

load

void load(Object key)
          throws CacheException
The load method provides a means to "pre load" the cache. This method will, asynchronously, load the specified object into the cache using the associated cacheloader. If the object already exists in the cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is encountered during the retrieving or loading of the object, an exception should be logged. If the "arg" argument is set, the arg object will be passed to the CacheLoader.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 get method will not distinguish returning a null stored in the cache and not finding the object in the cache. In both cases a null is returned.

Throws:
CacheException

loadAll

void loadAll(Collection keys)
             throws CacheException
The loadAll method provides a means to "pre load" objects into the cache. This method will, asynchronously, load the specified objects into the cache using the associated cache loader. If the an object already exists in the cache, no action is taken. If no loader is associated with the object, no object will be loaded into the cache. If a problem is encountered during the retrieving or loading of the objects, an exception (to be defined) should be logged. The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys". If the objects are not in the cache, the associated cache loader will be called. If no loader is associated with an object, a null is returned. If a problem is encountered during the retrieving or loading of the objects, an exception (to be defined) will be thrown. If the "arg" argument is set, the arg object will be passed to the CacheLoader.loadAll method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the loadAll method.

Throws:
CacheException

peek

Object peek(Object key)
The peek method will return the object associated with "key" if it currently exists (and is valid) in the cache. If not, a null is returned. With "peek" the CacheLoader will not be invoked and other caches in the system will not be searched.


put

Object put(Object key,
           Object value)
The put method adds the object "value" to the cache identified by the object "key".

Specified by:
put in interface Map

getCacheEntry

CacheEntry getCacheEntry(Object key)
Returns the CacheEntry object associated with the object identified by "key". If the object is not in the cache a null is returned.


getCacheStatistics

CacheStatistics getCacheStatistics()
Returns the CacheStatistics object associated with the cache. May return null if the cache does not support statistics gathering.


remove

Object remove(Object key)
The remove method will delete the object from the cache including the key, the associated value and the associated CacheStatistics object.

Specified by:
remove in interface Map

clear

void clear()
The clear method will remove all objects from the cache including the key, the associated value and the associated CacheStatistics object.

Specified by:
clear in interface Map

evict

void evict()
The evict method will remove objects from the cache that are no longer valid. Objects where the specified expiration time has been reached.


addListener

void addListener(CacheListener listener)
Add a listener to the list of cache listeners


removeListener

void removeListener(CacheListener listener)
Remove a listener from the list of cache listeners


ehcache

true