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 = Caching.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);
 

Consistency

Default Consistency

Consistency is described as if there exists a locking mechanism on each key. If a cache operation gets an exclusive read and write lock on a key, then all subsequent operations on that key will block until that lock is released. The consequences are that operations performed by a thread happen-before read or mutation operations performed by another thread, including threads in different Java Virtual Machines.

Transactional Consistency

Where are cache is transactional it will take on the semantics of the Transaction Isolation Level configured.

Further Consistency Modes

An implementation may support additional consistency models.

Since:

1.0

Author:

Greg Luck, Yannis Cosmadopoulos

Nested Class Summary

static interface	Cache.Entry<K,V> A cache entry (key-value pair).
static interface	Cache.EntryProcessor<K,V,T> Allows execution of code which may mutate a cache entry with exclusive access (including reads) to that entry.
static interface	Cache.MutableEntry<K,V> An accessor and mutator to the underlying Cache

Method Summary

void	clear() Clears the contents of the cache, without notifying listeners or CacheWriters.
boolean	containsKey(K key) Returns true if this cache contains a mapping for the specified key.
V	get(K key) Gets an entry from the cache.
Map<K,V>	getAll(Set<? 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) Associates the specified value with the specified key in this cache, returning an existing value if one existed.
V	getAndRemove(K 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.
Configuration<K,V>	getConfiguration() Returns a Configuration.
CacheMXBean	getMBean() Get the MBean for this cache.
String	getName() Return the name of the cache.
CacheStatisticsMXBean	getStatistics() Returns the CacheStatisticsMXBean MXBean associated with the cache.
<T> T	invokeEntryProcessor(K key, Cache.EntryProcessor<K,V,T> entryProcessor) Passes the cache entry associated with K to be passed to the entry processor.
Iterator<Cache.Entry<K,V>>	iterator() The ordering of iteration over entries is undefined.
Future<V>	load(K key) The load method provides a means to "pre-load" the cache.
Future<Map<K,? extends V>>	loadAll(Set<? 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<? super K,? super V> cacheEntryListener, boolean requireOldValue, CacheEntryEventFilter<? super K,? super V> cacheEntryFilter, boolean synchronous) Adds a listener to the notification service.
boolean	remove(K key) Removes the mapping for a key from this cache if it is present.
boolean	remove(K 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(Set<? 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 javax.cache.CacheLifecycle

getStatus, start, stop

Method Detail

get

V get(K key)

Gets an entry from the cache.

If the cache is configured read-through, and get would return null because the entry is missing from the cache, the Cache's CacheLoader is called which will attempt to load the entry.

Effects:

• Expiry - updates expiry time based on the Configuration ExpiryPolicy.
• Read-Through - will use the CacheLoader if enabled and key not present in 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(Set<? 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".

If the cache is configured read-through, and a get would return null because an entry is missing from the cache, the Cache's CacheLoader is called which will attempt to load the entry. This is done for each key in the collection for which this is the case. If an entry cannot be loaded for a given key, the key will not be present in the returned Map.

Parameters:

keys - The keys whose associated values are to be returned.

Returns:

A map of entries that were found for the given keys. Keys not found in the cache are not in the returned map.

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(K key)

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)

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 for the given key.

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,? extends V>> loadAll(Set<? extends K> keys)

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 for the given keys.

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.

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:

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

CacheStatisticsMXBean getStatistics()

Returns the CacheStatisticsMXBean 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)

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)

Associates the specified value with the specified key in this cache, returning an existing value if one existed.

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)

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 order in which the individual puts will occur is undefined. 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)

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(K key)

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(K key,
               V oldValue)

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(K key)

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)

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)

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)

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(Set<? extends K> keys)

Removes entries for the specified keys.

The order in which the individual removes will occur is undefined.

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()

Removes all of the mappings from this cache.

The order in which the individual removes will occur is undefined. This is potentially an expensive operation as listeners are invoked. Use #clear() to avoid this.

Throws:

IllegalStateException - if the cache is not Status.STARTED

CacheException - if there is a problem during the remove

See Also:

clear()

clear

void clear()

Clears the contents of the cache, without notifying listeners or CacheWriters.

Throws:

IllegalStateException - if the cache is not Status.STARTED

CacheException - if there is a problem during the remove

getConfiguration

Configuration<K,V> getConfiguration()

Returns a Configuration.

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

• Statistics must be mutable when status is Status.STARTED (Configuration.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 Configuration of this cache

registerCacheEntryListener

boolean registerCacheEntryListener(CacheEntryListener<? super K,? super V> cacheEntryListener,
                                   boolean requireOldValue,
                                   CacheEntryEventFilter<? super K,? super V> cacheEntryFilter,
                                   boolean synchronous)

Adds a listener to the notification service.

Parameters:

cacheEntryListener - The listener to add. Listeners fire synchronously in the execution path, and after the causing event. if a listener throws an exception it will be wrapped in a CacheException and propagated back to the caller. The listener may not be null

requireOldValue - whether the old value is supplied to CacheEntryEvent.

cacheEntryFilter - If present the listener will only be called if the filter evaluates to true. If null the listener is always called.

synchronous - whether the caller is blocked until the listener invocation completes.

Returns:

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

Throws:

NullPointerException - if the listener is null.

unregisterCacheEntryListener

boolean unregisterCacheEntryListener(CacheEntryListener<?,?> cacheEntryListener)

Removes a call back listener.

Parameters:

cacheEntryListener - the listener to remove

Returns:

true if the listener was present

invokeEntryProcessor

<T> T invokeEntryProcessor(K key,
                           Cache.EntryProcessor<K,V,T> entryProcessor)

Passes the cache entry associated with K to be passed to the entry processor. All operations performed by the processor will be done atomically i.e. all The processor will perform the operations against

Parameters:

key - the key to the entry

entryProcessor - the processor which will process the entry

Returns:

an object

Throws:

NullPointerException - if key or entryProcessor are null

IllegalStateException - if the cache is not Status.STARTED

See Also:

Cache.EntryProcessor

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.

iterator

Iterator<Cache.Entry<K,V>> iterator()

The ordering of iteration over entries is undefined.

During iteration, calling iterator.hasNext() determines if there is an available non-expired entry in the cache to which to iterate to, that of which will be returned by a subsequent call to next(). If hasNext() returns true, an infinite amount of time may elapse between the call to hasNext() and next(), without the prospective entry expirying. That is, it's impossible for hasNext() to return true and then a subsequent call to next() to fail on the same iterator.

During iteration, any entries that are a). read will have their appropriate CacheEntryReadListeners notified and b). removed will have their appropriate CacheEntryRemoveListeners notified.

Specified by:

iterator in interface Iterable<Cache.Entry<K,V>>

getMBean

CacheMXBean getMBean()

Get the MBean for this cache.

Returns:

the MBean TODO: Require implementations being tested to register MBeans where statistics are enabled so that they be found by ObjectName removing the need for this method.