com.j_spaces.javax.cache
Interface Cache

All Superinterfaces:

Map

All Known Subinterfaces:

IMap

All Known Implementing Classes:

com.j_spaces.map.AbstractMap, GSMapImpl

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.

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 uniquely the toString() method. 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.

All the methods that are inherited from Map might throw com.j_spaces.core.client.CacheException. This Exception extends RuntimeException in order to keep the Map API.

See Also:

CacheException, CacheEntry

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 and the associated value.
boolean	containsKey(Object key) Returns true if the cache contains the specified key.
boolean	containsValue(Object value) Returns true if this cache maps one or more keys to the specified value.
Set	entrySet() Returns a set view of the objects currently contained in the cache.
boolean	equals(Object obj) Equality is based on the Set returned by entrySet.
boolean	evict(Object key) The evict method will remove object from the cache the matches the provided key.
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".
int	hashCode() Returns the hash code value for this cache.
boolean	isEmpty() Return true if entrySet().isEmpty() return true.
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 map) 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() Returns the size of this map.
Collection	values() Returns a collection view of the values contained in this cache.

Method Detail

addListener

void addListener(CacheListener listener)

Add a listener to the list of cache listeners.
Optional, not supported by all the implementations, currently supported only by local cache.

Parameters:

listener - call back CacheListener

Throws:

UnsupportedOperationException - can be thrown by implementations that doesn't support this method

clear

void clear()

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

Specified by:

clear in interface Map

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

Parameters:

key - key whose presence in this cache is to be tested.

Returns:

true, if the cache contains the specified key.

containsValue

boolean containsValue(Object value)

Returns true if this cache maps one or more keys to the specified value. 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:

containsValue in interface Map

Parameters:

value - value whose presence in this cache is to be tested.

Returns:

true, if the cache contains the specified value.

entrySet

Set entrySet()

Returns a set view of the objects currently contained in the cache. 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:

entrySet in interface Map

Returns:

a set of CacheEntry

equals

boolean equals(Object obj)

Equality is based on the Set returned by entrySet.

Specified by:

equals in interface Map

Overrides:

equals in class Object

Parameters:

obj - the Cache to check

Returns:

true, if two caches returns the same entrySet().

evict

boolean evict(Object key)

The evict method will remove object from the cache the matches the provided key.

Parameters:

key - the key to evict

Returns:

true, if the key was evicted

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.

Specified by:

get in interface Map

Parameters:

key - key whose associated value is to be returned.

Returns:

the value to which this cache maps the specified key, or null if the cache contains no mapping for this key.

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.

Parameters:

keys - keys whose associated values are to be returned.

Returns:

Map of the objects associated with the Collection of keys

Throws:

CacheException - error accord while loading

getCacheEntry

CacheEntry getCacheEntry(Object key)

Returns the CacheEntry object associated with the object identified by "key".

Parameters:

key - key whose associated value is to be returned.

Returns:

the CacheEntry to which this cache maps the specified key, or null if the cache contains no mapping for this key.

hashCode

int hashCode()

Returns the hash code value for this cache.

Specified by:

hashCode in interface Map

Overrides:

hashCode in class Object

Returns:

the hash code

isEmpty

boolean isEmpty()

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

Specified by:

isEmpty in interface Map

Returns:

true if empty

keySet

Set keySet()

Returns a set view of the keys currently contained in the cache. 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:

keySet in interface Map

Returns:

set of the keys

load

void load(Object key)
          throws CacheException

The load method provides a means to "pre load" the cache. This method will, 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.

Parameters:

key - key whose associated value is to be loaded.

Throws:

CacheException - error accord while loading

loadAll

void loadAll(Collection keys)
             throws CacheException

The loadAll method provides a means to "pre load" objects into the cache. This method will, 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.

Parameters:

keys - keys' Collection whose associated value to be loaded using the associated CacheLoader if this cache doesn't contain it.

Throws:

CacheException - error accord while loading

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. 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 associated value is to be peek.

Returns:

the value to which this cache maps the specified key, or null if the cache contains no mapping for this key.

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

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for key.

putAll

void putAll(Map map)

Copies all of the mappings from the specified map to the cache.

Specified by:

putAll in interface Map

Parameters:

map - A map of key and values to be copy into the cache

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

Parameters:

key - key whose associated value is to be removed.

Returns:

previous value associated with specified key, or null if there was no mapping for key.

removeListener

void removeListener(CacheListener listener)

Remove a listener from the list of cache listeners.
Optional, not supported by all the implementations, currently supported only by local cache

Parameters:

listener - the CacheListener to remove

Throws:

UnsupportedOperationException - can be thrown by implementations that doesn't support this method

size

int size()

Returns the size of this map. 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:

size in interface Map

Returns:

the number of key-value mappings in this cache.

values

Collection values()

Returns a collection view of the values contained in this cache. 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:

values in interface Map

Returns:

a collection view of the values contained in this cache.