javax.cache
Interface Cache<K,V>

Type Parameters:

K - the type of keys maintained by this cache

V - the type of cached values

All Superinterfaces:

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

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

A Cache provides storage of data for later fast retrieval.

This Cache interface is based on ConcurrentMap with some modifications for fast distributed performance.

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.

Caches use generics throughout providing a level of type safety akin to the collections package.

Cache implements Iterable for Cache.Entry, 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.

The Cache API also provides:

• read-through caching
• write-through caching
• cache loading
• cache listeners
• statistics
• lifecycle
• configuration

Though not visible in the Cache interface caches may be optionally transactional.

User programs may make use of caching annotations to interact with a cache.

A simple example of how to use a cache is:

 String cacheName = "sampleCache";
 CacheManager cacheManager = CacheManagerFactory.getCacheManager();
 Cache<Integer, Date> cache = cacheManager.getCache(cacheName);
 if (cache == null) {
   cache = cacheManager.<Integer,Date>createCacheBuilder(cacheName).build();
 }
 Date value1 = new Date();
 Integer key = 1;
 cache.put(key, value1);
 Date value2 = cache.get(key);
 

Since:

1.0

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	getAndPut(K key, V value) Atomically 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.
V	getAndRemove(Object key) Atomically removes the entry for a key only if currently mapped to a given value.
V	getAndReplace(K key, V value) Atomically replaces the entry for a key only if currently mapped to some value.
CacheManager	getCacheManager() Gets the CacheManager managing this cache.
CacheConfiguration	getConfiguration() Returns a CacheConfiguration.
String	getName() Return the name of the cache.
CacheStatistics	getStatistics() Returns the CacheStatistics MXBean associated with the cache.
Future<V>	load(K key) The load method provides a means to "pre load" the cache.
Future<Map<K,V>>	loadAll(Collection<? extends K> keys) 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) Atomically associates the specified key with the given value if it is not already associated with a value.
boolean	registerCacheEntryListener(CacheEntryListener<K,V> cacheEntryListener, NotificationScope scope, boolean synchronous) Adds a listener to the notification service.
boolean	remove(Object key) Removes the mapping for a key from this cache if it is present.
boolean	remove(Object key, V oldValue) Atomically removes the mapping for a key only if currently mapped to the given value.
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) Atomically replaces the entry for a key only if currently mapped to some value.
boolean	replace(K key, V oldValue, V newValue) Atomically replaces the entry for a key only if currently mapped to a given value.
boolean	unregisterCacheEntryListener(CacheEntryListener<?,?> cacheEntryListener) Removes a call back listener.
<T> T	unwrap(Class<T> cls) Return an object of the specified type to allow access to the provider-specific API.

Methods inherited from interface java.lang.Iterable

iterator

Methods inherited from interface javax.cache.CacheLifecycle

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

IllegalStateException - if the cache is not Status.STARTED

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

IllegalStateException - if the cache is not Status.STARTED

CacheException - it there is a problem checking the mapping

See Also:

Map.containsKey(Object)

load

Future<V> load(K 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 and null is returned. If no loader is associated with the cache 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

Parameters:

key - the key

Returns:

a Future which can be used to monitor execution.

Throws:

NullPointerException - if key is null.

IllegalStateException - if the cache is not Status.STARTED

CacheException - if there is a problem doing the load

loadAll

Future<Map<K,V>> loadAll(Collection<? extends K> 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.

Parameters:

keys - the keys

Returns:

a Future which can be used to monitor execution

Throws:

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

IllegalStateException - if the cache is not Status.STARTED

CacheException - if there is a problem doing the load

getStatistics

CacheStatistics getStatistics()

Returns the CacheStatistics MXBean associated with the cache. May return null if the cache does not support statistics gathering.

Returns:

the CacheStatisticsMBean

Throws:

IllegalStateException - if the cache is not Status.STARTED

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

IllegalStateException - if the cache is not Status.STARTED

CacheException - if there is a problem doing the put

See Also:

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

getAndPut

V getAndPut(K key,
            V value)
            throws CacheException

Atomically 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.)

The the previous value is returned, or null if there was no value associated with the key previously.

Parameters:

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

value - value to be associated with the specified key

Returns:

the value associated with the key at the start of the operation or null if none was associated

Throws:

NullPointerException - if key is null or if value is null

IllegalStateException - if the cache is not Status.STARTED

CacheException - if there is a problem doing the put

See Also:

Map.put(Object, Object), 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.

IllegalStateException - if the cache is not Status.STARTED

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

Atomically associates the specified key with the given value if it is not already associated with a 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

IllegalStateException - if the cache is not Status.STARTED

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

IllegalStateException - if the cache is not Status.STARTED

CacheException - if there is a problem doing the put

See Also:

Map.remove(Object)

remove

boolean remove(Object key,
               V oldValue)
               throws CacheException

Atomically removes the mapping for a key only if currently mapped to the given value.

This is equivalent to

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

except that the action is performed atomically.

Parameters:

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

oldValue - value expected to be associated with the specified key

Returns:

returns false if there was no matching key

Throws:

NullPointerException - if key is null

IllegalStateException - if the cache is not Status.STARTED

CacheException - if there is a problem doing the put

See Also:

Map.remove(Object)

getAndRemove

V getAndRemove(Object key)
               throws CacheException

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

This is equivalent to

   if (cache.containsKey(key)) {
       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:

the value if one existed or null if no mapping existed for this key

Throws:

NullPointerException - if the specified key or value is null.

IllegalStateException - if the cache is not Status.STARTED

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

Atomically 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

IllegalStateException - if the cache is not Status.STARTED

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

Atomically 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

IllegalStateException - if the cache is not Status.STARTED

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

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

Throws:

NullPointerException - if key is null or if value is null

IllegalStateException - if the cache is not Status.STARTED

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

IllegalStateException - if the cache is not Status.STARTED

CacheException - if there is a problem during the remove

removeAll

void removeAll()
               throws CacheException

Removes all of the mappings from this cache.

This is potentially an expensive operation.

Throws:

IllegalStateException - if the cache is not Status.STARTED

CacheException - if there is a problem during the remove

See Also:

Map.clear()

getConfiguration

CacheConfiguration getConfiguration()

Returns a CacheConfiguration.

When status is Status.STARTED an implementation must respect the following:

• Statistics must be mutable when status is Status.STARTED (CacheConfiguration.setStatisticsEnabled(boolean))

If an implementation permits mutation of configuration to a running cache, those changes must be reflected in the cache. In the case where mutation is not allowed InvalidConfigurationException must be thrown on an attempt to mutate the configuration.

Returns:

the CacheConfiguration of this cache

registerCacheEntryListener

boolean registerCacheEntryListener(CacheEntryListener<K,V> cacheEntryListener,
                                   NotificationScope scope,
                                   boolean synchronous)

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.

synchronous - whether to listener should be invoked synchronously

Returns:

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

Throws:

NullPointerException - if any of the arguments are null.

unregisterCacheEntryListener

boolean unregisterCacheEntryListener(CacheEntryListener<?,?> cacheEntryListener)

Removes a call back listener.

Parameters:

cacheEntryListener - the listener to remove

Returns:

true if the listener was present

getName

String getName()

Return the name of the cache.

Returns:

the name of the cache.

getCacheManager

CacheManager getCacheManager()

Gets the CacheManager managing this cache.

A cache can be in only one CacheManager.

Returns:

the manager

unwrap

<T> T unwrap(Class<T> cls)

Return an object of the specified type to allow access to the provider-specific API. If the provider's implementation does not support the specified class, the IllegalArgumentException is thrown.

Parameters:

cls - he class of the object to be returned. This is normally either the underlying implementation class or an interface that it implements.

Returns:

an instance of the specified class

Throws:

IllegalArgumentException - if the provider doesn't support the specified class.