javax.cache
Interface Cache<K,V>

Type Parameters:

K - the type of keys maintained by this map

V - the type of mapped values

All Superinterfaces:

Iterable<Cache.Entry<K,V>>, Lifecycle

public interface Cache<K,V>
extends Iterable<Cache.Entry<K,V>>, Lifecycle

A Cache provides temporary storage for later fast retrieval.

The interface is map-like and will be familiar. However the map-like methods have been modified to enable efficient implementation of distributed caches.

The API provides the atomic operations from ConcurrentMap.

The API provides batch operations suited to network storage.

A Cache does not allow null keys or values. Attempts to store a null value or to use a null key either in a get or put operation will result in a NullPointerException.

OPEN ISSUES: - should all methods throw CacheException? If not what? - Cache Statistics? JMX? - cache loading defined. warming which is in the cache lifecycle is not.

These methods are ?blocking synchronous?. We need to define what that means.

Cache implements Iterable, providing support for simplified iteration. However iteration should be used with caution. It is an O(n) operation and may be slow on large or distributed caches.

Since:

1.7

Author:

Greg Luck, Yannis Cosmadopoulos

Nested Class Summary

static interface

Cache.Entry<K,V> A cache entry (key-value pair).

Method Summary

boolean	containsKey(Object key) Returns true if this cache contains a mapping for the specified key.
V	get(Object key) Gets an entry from the cache.
Map<K,V>	getAll(Collection<? extends K> keys) The getAll method will return, from the cache, a Map of the objects associated with the Collection of keys in argument "keys".
V	getAndRemove(Object key) Removes the entry for a key only if currently mapped to a given value.
V	getAndReplace(K key, V value) Replaces the entry for a key only if currently mapped to some value.
CacheManager	getCacheManager() Gets the CacheManager managing this cache.
String	getCacheName() Return the name of the cache.
CacheStatisticsMBean	getCacheStatistics() Returns the CacheStatisticsMBean object associated with the cache.
CacheConfiguration	getConfiguration() Returns a CacheConfiguration.
Future<V>	load(K key, CacheLoader<K,V> specificLoader, Object loaderArgument) The load method provides a means to "pre load" the cache.
Future<Map<K,V>>	loadAll(Collection<? extends K> keys, CacheLoader<K,V> specificLoader, Object loaderArgument) The loadAll method provides a means to "pre load" objects into the cache.
void	put(K key, V value) Associates the specified value with the specified key in this cache If the cache previously contained a mapping for the key, the old value is replaced by the specified value.
void	putAll(Map<? extends K,? extends V> map) Copies all of the mappings from the specified map to this cache.
boolean	putIfAbsent(K key, V value) If the specified key is not already associated with a value, associate it with the given value.
boolean	registerCacheEntryListener(CacheEntryListener cacheEntryListener, NotificationScope scope) Adds a listener to the notification service.
boolean	remove(Object key) Removes the mapping for a key from this cache if it is present.
void	removeAll() Removes all of the mappings from this cache.
void	removeAll(Collection<? extends K> keys) Removes entries for the specified keys
boolean	replace(K key, V value) Replaces the entry for a key only if currently mapped to some value.
boolean	replace(K key, V oldValue, V newValue) Replaces the entry for a key only if currently mapped to a given value.
boolean	unregisterCacheEntryListener(CacheEntryListener cacheEntryListener) Removes a call back listener.

Methods inherited from interface java.lang.Iterable

iterator

Methods inherited from interface javax.cache.Lifecycle

getStatus, start, stop

Method Detail

get

V get(Object key)
      throws CacheException

Gets an entry from the cache.

Parameters:

key - the key whose associated value is to be returned

Returns:

the element, or null, if it does not exist.

Throws:

IllegalStateException - if the cache is not Status.STARTED

NullPointerException - if the key is null

CacheException - if there is a problem fetching the value

See Also:

Map.get(Object)

getAll

Map<K,V> getAll(Collection<? extends K> 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 - The keys whose associated values are to be returned.

Returns:

The entries for the specified keys.

Throws:

NullPointerException - if keys is null or if keys contains a null

CacheException - if there is a problem fetching the values.

containsKey

boolean containsKey(Object key)
                    throws CacheException

Returns true if this cache contains a mapping for the specified key. More formally, returns true if and only if this cache contains a mapping for a key k such that key.equals(k). (There can be at most one such mapping.)

Parameters:

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

Returns:

true if this map contains a mapping for the specified key

Throws:

NullPointerException - if key is null

CacheException - it there is a problem checking the mapping

See Also:

Map.containsKey(Object)

load

Future<V> load(K key,
               CacheLoader<K,V> specificLoader,
               Object loaderArgument)
               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 and null is returned. If no loader is associated with the cache, and specific loader is null, no object will be loaded into the cache and null is returned. If a problem is encountered during the retrieving or loading of the object, an exception must be propagated on Future.get() as a ExecutionException

If the "arg" argument is set, the arg object will be passed to the CacheLoader.load(Object, Object) method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the load method.

Parameters:

key - the key

specificLoader - a specific loader to use. If null the default loader is used.

loaderArgument - provision for additional parameters to be passed to the loader

Returns:

a Future which can be used to monitor execution.

Throws:

NullPointerException - if key is null.

CacheException - if there is a problem doing the load

loadAll

Future<Map<K,V>> loadAll(Collection<? extends K> keys,
                         CacheLoader<K,V> specificLoader,
                         Object loaderArgument)
                         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(java.util.Collection, Object) method. The cache will not dereference the object. If no "arg" value is provided a null will be passed to the CacheLoader loadAll method.

Parameters:

keys - the keys

specificLoader - a specific loader to use. If null the default loader is used.

loaderArgument - provision for additional parameters to be passed to the loader

Returns:

a Future which can be used to monitor execution

Throws:

NullPointerException - if keys is null or if keys contains a null.

CacheException - if there is a problem doing the load

getCacheStatistics

CacheStatisticsMBean getCacheStatistics()

Returns the CacheStatisticsMBean object associated with the cache. May return null if the cache does not support statistics gathering.

Returns:

the CacheStatisticsMBean

put

void put(K key,
         V value)
         throws CacheException

Associates the specified value with the specified key in this cache If the cache previously contained a mapping for the key, the old value is replaced by the specified value. (A cache c is said to contain a mapping for a key k if and only if c.containsKey(k) would return true.)

In contrast to the corresponding Map operation, does not return the previous value.

Parameters:

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

value - value to be associated with the specified key

Throws:

NullPointerException - if key is null or if value is null

CacheException - if there is a problem doing the put

See Also:

Map.put(Object, Object), getAndReplace(Object, Object)

putAll

void putAll(Map<? extends K,? extends V> map)
            throws CacheException

Copies all of the mappings from the specified map to this cache. The effect of this call is equivalent to that of calling put(k, v) on this cache once for each mapping from key k to value v in the specified map. The behavior of this operation is undefined if the specified cache or map is modified while the operation is in progress.

Parameters:

map - mappings to be stored in this cache

Throws:

NullPointerException - if map is null or if map contains null keys or values.

CacheException - if there is a problem doing the put

See Also:

Map.putAll(java.util.Map)

putIfAbsent

boolean putIfAbsent(K key,
                    V value)
                    throws CacheException

If the specified key is not already associated with a value, associate it with the given value. This is equivalent to

   if (!cache.containsKey(key)) {}
       cache.put(key, value);
       return true;
   } else {
       return false;
   }

except that the action is performed atomically.

In contrast to the corresponding ConcurrentMap operation, does not return the previous value.

Parameters:

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

value - value to be associated with the specified key

Returns:

true if a value was set.

Throws:

NullPointerException - if key is null or value is null

CacheException - if there is a problem doing the put

See Also:

ConcurrentMap.putIfAbsent(Object, Object)

remove

boolean remove(Object key)
               throws CacheException

Removes the mapping for a key from this cache if it is present. More formally, if this cache contains a mapping from key k to value v such that (key==null ? k==null : key.equals(k)), that mapping is removed. (The cache can contain at most one such mapping.)

Returns true if this cache previously associated the key, or false if the cache contained no mapping for the key.

The cache will not contain a mapping for the specified key once the call returns.

Parameters:

key - key whose mapping is to be removed from the cache

Returns:

returns false if there was no matching key

Throws:

NullPointerException - if key is null

CacheException - if there is a problem doing the put

See Also:

Map.remove(Object)

getAndRemove

V getAndRemove(Object key)
               throws CacheException

Removes the entry for a key only if currently mapped to a given value.

This is equivalent to

   if (cache.containsKey(key) && cache.get(key).equals(value)) {
       V oldValue = cache.get(key);
       cache.remove(key);
       return oldValue;
   } else {
       return null;
   }

except that the action is performed atomically.

Parameters:

key - key with which the specified value is associated

Returns:

true if the value was removed

Throws:

UnsupportedOperationException - if the getAndRemove operation is not supported by this cache

ClassCastException - if the key or value is of an inappropriate type for this cache (optional)

NullPointerException - if the specified key is null.

CacheException - if there is a problem during the remove

See Also:

Map.remove(Object)

replace

boolean replace(K key,
                V oldValue,
                V newValue)
                throws CacheException

Replaces the entry for a key only if currently mapped to a given value. This is equivalent to

   if (cache.containsKey(key) && cache.get(key).equals(oldValue)) {
       cache.put(key, newValue);
       return true;
   } else {
       return false;
   }

except that the action is performed atomically.

Parameters:

key - key with which the specified value is associated

oldValue - value expected to be associated with the specified key

newValue - value to be associated with the specified key

Returns:

true if the value was replaced

Throws:

NullPointerException - if key is null or if the values are null

CacheException - if there is a problem during the replace

See Also:

ConcurrentMap.replace(Object, Object, Object)

replace

boolean replace(K key,
                V value)
                throws CacheException

Replaces the entry for a key only if currently mapped to some value. This is equivalent to

   if (cache.containsKey(key)) {
       cache.put(key, value);
       return true;
   } else {
       return false;
   }

except that the action is performed atomically.

In contrast to the corresponding ConcurrentMap operation, does not return the previous value.

Parameters:

key - key with which the specified value is associated

value - value to be associated with the specified key

Returns:

true if the value was replaced

Throws:

NullPointerException - if key is null or if value is null

CacheException - if there is a problem during the replace

See Also:

getAndReplace(Object, Object), ConcurrentMap.replace(Object, Object)

getAndReplace

V getAndReplace(K key,
                V value)
                throws CacheException

Replaces the entry for a key only if currently mapped to some value. This is equivalent to

   if (cache.containsKey(key)) {
       V value = cache.get(key, value);
       cache.put(key, value);
       return value;
   } else {
       return null;
   }

except that the action is performed atomically.

Parameters:

key - key with which the specified value is associated

value - value to be associated with the specified key

Returns:

the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the cache previously associated null with the key, if the implementation supports null values.)

Throws:

NullPointerException - if key is null or if value is null

CacheException - if there is a problem during the replace

See Also:

ConcurrentMap.replace(Object, Object)

removeAll

void removeAll(Collection<? extends K> keys)
               throws CacheException

Removes entries for the specified keys

Parameters:

keys - the keys to remove

Throws:

NullPointerException - if keys is null or if it contains a null key

CacheException - if there is a problem during the remove

removeAll

void removeAll()
               throws CacheException

Removes all of the mappings from this cache. The cache will be empty after this call returns.

This is potentially an expensive operation.

Throws:

CacheException - if there is a problem during the remove

See Also:

Map.clear()

getConfiguration

CacheConfiguration getConfiguration()

Returns a CacheConfiguration.

Whether the configuration is mutable after the cache has Status.STARTED is up to the implementation, however the configuration cannot be changed unless the changes are applied to the cache.

Returns:

the CacheConfiguration

registerCacheEntryListener

boolean registerCacheEntryListener(CacheEntryListener cacheEntryListener,
                                   NotificationScope scope)

Adds a listener to the notification service. No guarantee is made that listeners will be notified in the order they were added.

Parameters:

cacheEntryListener - The listener to add. A listener may be added only once, so the same listener with two difference scopes is not allowed.

scope - The notification scope. If this parameter is null, the NotificationScope.ALL scope is used.

Returns:

true if the listener is being added and was not already added

unregisterCacheEntryListener

boolean unregisterCacheEntryListener(CacheEntryListener cacheEntryListener)

Removes a call back listener.

Parameters:

cacheEntryListener - the listener to remove

Returns:

true if the listener was present

getCacheName

String getCacheName()

Return the name of the cache.

Returns:

the name of the cache.

getCacheManager

CacheManager getCacheManager()

Gets the CacheManager managing this cache. For a newly created cache this will be null until it has been added to a CacheManager.

A cache can be in only have one CacheManager.

Returns:

the manager or null if there is none