org.ajax4jsf.cache
Interface Cache

public interface Cache

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.

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(java.lang.Object key) Returns true if the cache contains the specified key.
boolean	containsValue(java.lang.Object value)
java.util.Set<java.util.Map.Entry<java.lang.Object,java.lang.Object>>	entrySet() Returns a set view of the objects currently contained in the cache.
boolean	equals(java.lang.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.
java.lang.Object	get(java.lang.Object key, java.lang.Object context) The get method will return, from the cache, the object associated with the argument "key".
CacheEntry	getCacheEntry(java.lang.Object key) Returns the CacheEntry object associated with the object identified by "key".
int	hashCode()
boolean	isEmpty()
java.util.Set<java.lang.Object>	keySet() Returns a set view of the keys currently contained in the cache.
void	load(java.lang.Object key, java.lang.Object context) The load method provides a means to "pre load" the cache.
java.lang.Object	peek(java.lang.Object key) The peek method will return the object associated with "key" if it currently exists (and is valid) in the cache.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) The put method adds the object "value" to the cache identified by the object "key".
void	putAll(java.util.Map<? extends java.lang.Object,? extends java.lang.Object> t) Copies all of the mappings from the specified map to the cache.
java.lang.Object	remove(java.lang.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()
java.util.Collection<java.lang.Object>	values()

Method Detail

containsKey

boolean containsKey(java.lang.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.

Returns:

true, if the cache contains the specified key.

containsValue

boolean containsValue(java.lang.Object value)

Returns:

true if the cache contains one or more keys to the specified value.

entrySet

java.util.Set<java.util.Map.Entry<java.lang.Object,java.lang.Object>> 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.

equals

boolean equals(java.lang.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.

Overrides:

equals in class java.lang.Object

hashCode

int hashCode()

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code value for this the cache.

isEmpty

boolean isEmpty()

Returns:

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

keySet

java.util.Set<java.lang.Object> 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.

putAll

void putAll(java.util.Map<? extends java.lang.Object,? extends java.lang.Object> 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.

size

int size()

Returns:

the number of objects in the cache. This should be the same value as entrySet().size();

values

java.util.Collection<java.lang.Object> values()

Returns:

a collection view of the values contained in the cache.

get

java.lang.Object get(java.lang.Object key,
                     java.lang.Object context)
                     throws CacheException

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.

Throws:

CacheException

load

void load(java.lang.Object key,
          java.lang.Object context)
          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

peek

java.lang.Object peek(java.lang.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

java.lang.Object put(java.lang.Object key,
                     java.lang.Object value)

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

getCacheEntry

CacheEntry getCacheEntry(java.lang.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.

remove

java.lang.Object remove(java.lang.Object key)

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

clear

void clear()

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

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