javax.cache

Interface Cache<K,V>

Type Parameters:

K - the type of key

V - the type of value

All Superinterfaces:

AutoCloseable, Closeable, Iterable<Cache.Entry<K,V>>

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

A Cache is a Map-like data structure that provides temporary storage of application data.

Like Maps, Caches

1. store key-value pairs, each referred to as an Cache.Entry
2. allow use of Java Generics to improve application type-safety
3. are Iterable

Unlike Maps, Caches

1. do not allow null keys or values. Attempts to use null will result in a NullPointerException
2. provide the ability to read values from a CacheLoader (read-through-caching) when a value being requested is not in a cache
3. provide the ability to write values to a CacheWriter (write-through-caching) when a value being created/updated/removed from a cache
4. provide the ability to observe cache entry changes
5. may capture and measure operational statistics

A simple example of how to use a cache is:

 String cacheName = "sampleCache";
 CachingProvider provider = Caching.getCachingProvider();
 CacheManager manager = provider.getCacheManager();
 Cache<Integer, Date> cache = manager.getCache(cacheName, Integer.class,
                                                     Date.class);
 Date value1 = new Date();
 Integer key = 1;
 cache.put(key, value1);
 Date value2 = cache.get(key);
 

Since:

1.0

Author:

Greg Luck, Yannis Cosmadopoulos, Brian Oliver

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Cache.Entry<K,V> A cache entry (key-value pair).

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Clears the contents of the cache, without notifying listeners or CacheWriters.
void	close() Closing a Cache signals to the CacheManager that produced or owns the Cache that it should no longer be managed.
boolean	containsKey(K key) Determines if the Cache contains an entry for the specified key.
void	deregisterCacheEntryListener(CacheEntryListenerConfiguration<K,V> cacheEntryListenerConfiguration) Deregisters a listener, using the CacheEntryListenerConfiguration that was used to register it.
V	get(K key) Gets an entry from the cache.
Map<K,V>	getAll(Set<? extends K> keys) Gets a collection of entries from the Cache, returning them as Map of the values associated with the set of keys requested.
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 some value.
V	getAndReplace(K key, V value) Atomically replaces the value for a given key if and only if there is a value currently mapped by the key.
CacheManager	getCacheManager() Gets the CacheManager that owns and manages the Cache.
<C extends Configuration<K,V>> C	getConfiguration(Class<C> clazz) Provides a standard way to access the configuration of a cache using JCache configuration or additional proprietary configuration.
String	getName() Return the name of the cache.
<T> T	invoke(K key, EntryProcessor<K,V,T> entryProcessor, Object... arguments) Invokes an EntryProcessor against the Cache.Entry specified by the provided key.
<T> Map<K,EntryProcessorResult<T>>	invokeAll(Set<? extends K> keys, EntryProcessor<K,V,T> entryProcessor, Object... arguments) Invokes an EntryProcessor against the set of Cache.Entrys specified by the set of keys.
boolean	isClosed() Determines whether this Cache instance has been closed.
Iterator<Cache.Entry<K,V>>	iterator()
void	loadAll(Set<? extends K> keys, boolean replaceExistingValues, CompletionListener completionListener) Asynchronously loads the specified entries into the cache using the configured CacheLoader for the given keys.
void	put(K key, V value) Associates the specified value with the specified key in the cache.
void	putAll(Map<? extends K,? extends V> map) Copies all of the entries from the specified map to the 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.
void	registerCacheEntryListener(CacheEntryListenerConfiguration<K,V> cacheEntryListenerConfiguration) Registers a CacheEntryListener.
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.
<T> T	unwrap(Class<T> clazz) Provides a standard way to access the underlying concrete caching implementation to provide access to further, proprietary features.

Method Detail

get

V get(K key)

Gets an entry from the cache.

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

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

NullPointerException - if the key is null

CacheException - if there is a problem fetching the value

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

getAll

Map<K,V> getAll(Set<? extends K> keys)

Gets a collection of entries from the Cache, returning them as Map of the values associated with the set of keys requested.

If the cache is configured read-through, and a get for a key would return null because an entry is missing from the cache, the Cache's CacheLoader is called in an attempt to load the entry. 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 isClosed()

CacheException - if there is a problem fetching the values

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

containsKey

boolean containsKey(K key)

Determines if the Cache contains an entry 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 isClosed()

CacheException - it there is a problem checking the mapping

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

Map.containsKey(Object)

loadAll

void loadAll(Set<? extends K> keys,
           boolean replaceExistingValues,
           CompletionListener completionListener)

Asynchronously loads the specified entries into the cache using the configured CacheLoader for the given keys.

If an entry for a key already exists in the Cache, a value will be loaded if and only if replaceExistingValues is true. If no loader is configured for the cache, no objects will be loaded. If a problem is encountered during the retrieving or loading of the objects, an exception is provided to the CompletionListener. Once the operation has completed, the specified CompletionListener is notified.

Implementations may choose to load multiple keys from the provided Set in parallel. Iteration however must not occur in parallel, thus allow for non-thread-safe Sets to be used.

The thread on which the completion listener is called is implementation dependent. An implementation may also choose to serialize calls to different CompletionListeners rather than use a thread per CompletionListener.

Parameters:

keys - the keys to load

replaceExistingValues - when true existing values in the Cache will be replaced by those loaded from a CacheLoader

completionListener - the CompletionListener (may be null)

Throws:

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

IllegalStateException - if the cache is isClosed()

CacheException - thrown if there is a problem performing the load. This may also be thrown on calling if there are insufficient threads available to perform the load.

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

put

void put(K key,
       V value)

Associates the specified value with the specified key in the 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.)

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

CacheException - if there is a problem doing the put

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

Map.put(Object, Object), getAndPut(Object, Object), getAndReplace(Object, Object), CacheWriter.write(javax.cache.Cache.Entry<? extends K, ? extends V>)

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

CacheException - if there is a problem doing the put

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

put(Object, Object), getAndReplace(Object, Object), CacheWriter.write(javax.cache.Cache.Entry<? extends K, ? extends V>)

putAll

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

Copies all of the entries from the specified map to the 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 occur is undefined.

The behavior of this operation is undefined if entries in the cache corresponding to entries in the map are modified or removed while this operation is in progress. or if map is modified while the operation is in progress.

In Default Consistency mode, individual puts occur atomically but not the entire putAll. Listeners may observe individual updates.

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

CacheException - if there is a problem doing the put.

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

CacheWriter.writeAll(java.util.Collection<javax.cache.Cache.Entry<? extends K, ? extends V>>)

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.

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

CacheException - if there is a problem doing the put

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

CacheWriter.write(javax.cache.Cache.Entry<? extends K, ? extends V>)

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

CacheException - if there is a problem doing the remove

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

CacheWriter.delete(java.lang.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) && equals(cache.get(key), 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 isClosed()

CacheException - if there is a problem doing the remove

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

CacheWriter.delete(java.lang.Object)

getAndRemove

V getAndRemove(K key)

Atomically removes the entry for a key only if currently mapped to some 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 isClosed()

CacheException - if there is a problem during the remove

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

CacheWriter.delete(java.lang.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) && equals(cache.get(key), 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 isClosed()

CacheException - if there is a problem during the replace

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

CacheWriter.write(javax.cache.Cache.Entry<? extends K, ? extends V>)

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.

Parameters:

key - the key with which the specified value is associated

value - the 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 isClosed()

CacheException - if there is a problem during the replace

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

getAndReplace(Object, Object), CacheWriter.write(javax.cache.Cache.Entry<? extends K, ? extends V>)

getAndReplace

V getAndReplace(K key,
              V value)

Atomically replaces the value for a given key if and only if there is a value currently mapped by the key.

This is equivalent to

 if (cache.containsKey(key)) {
   V oldValue = cache.get(key);
   cache.put(key, value);
   return oldValue;
 } 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 isClosed()

CacheException - if there is a problem during the replace

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

ConcurrentMap.replace(Object, Object), CacheWriter.write(javax.cache.Cache.Entry<? extends K, ? extends V>)

removeAll

void removeAll(Set<? extends K> keys)

Removes entries for the specified keys.

The order in which the individual entries are removed is undefined.

For every entry in the key set, the following are called:

• any registered CacheEntryRemovedListeners
• if the cache is a write-through cache, the CacheWriter

If the key set is empty, the CacheWriter is not called.

Parameters:

keys - the keys to remove

Throws:

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

IllegalStateException - if the cache is isClosed()

CacheException - if there is a problem during the remove

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

CacheWriter.deleteAll(java.util.Collection<?>)

removeAll

void removeAll()

Removes all of the mappings from this cache.

The order that the individual entries are removed is undefined.

For every mapping that exists the following are called:

• any registered CacheEntryRemovedListeners
• if the cache is a write-through cache, the CacheWriter

If the cache is empty, the CacheWriter is not called.

This is potentially an expensive operation as listeners are invoked. Use clear() to avoid this.

Throws:

IllegalStateException - if the cache is isClosed()

CacheException - if there is a problem during the remove

See Also:

clear(), CacheWriter.deleteAll(java.util.Collection<?>)

clear

void clear()

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

Throws:

IllegalStateException - if the cache is isClosed()

CacheException - if there is a problem during the clear

getConfiguration

<C extends Configuration<K,V>> C getConfiguration(Class<C> clazz)

Provides a standard way to access the configuration of a cache using JCache configuration or additional proprietary configuration.

The returned value must be immutable.

If the provider's implementation does not support the specified class, the IllegalArgumentException is thrown.

Parameters:

clazz - the configuration interface or class to return. This includes Configuration.class and CompleteConfigurations.

Returns:

the requested implementation of Configuration

Throws:

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

invoke

<T> T invoke(K key,
           EntryProcessor<K,V,T> entryProcessor,
           Object... arguments)
         throws EntryProcessorException

Invokes an EntryProcessor against the Cache.Entry specified by the provided key. If an Cache.Entry does not exist for the specified key, an attempt is made to load it (if a loader is configured) or a surrogate Cache.Entry, consisting of the key with a null value is used instead.

Parameters:

key - the key to the entry

entryProcessor - the EntryProcessor to invoke

arguments - additional arguments to pass to the EntryProcessor

Returns:

the result of the processing, if any, defined by the EntryProcessor implementation

Throws:

NullPointerException - if key or EntryProcessor is null

IllegalStateException - if the cache is isClosed()

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

EntryProcessorException - if an exception is thrown by the EntryProcessor, a Caching Implementation must wrap any Exception thrown wrapped in an EntryProcessorException.

See Also:

EntryProcessor

invokeAll

<T> Map<K,EntryProcessorResult<T>> invokeAll(Set<? extends K> keys,
                                           EntryProcessor<K,V,T> entryProcessor,
                                           Object... arguments)

Invokes an EntryProcessor against the set of Cache.Entrys specified by the set of keys.

If an Cache.Entry does not exist for the specified key, an attempt is made to load it (if a loader is configured) or a surrogate Cache.Entry, consisting of the key and a value of null is provided.

The order that the entries for the keys are processed is undefined. Implementations may choose to process the entries in any order, including concurrently. Furthermore there is no guarantee implementations will use the same EntryProcessor instance to process each entry, as the case may be in a non-local cache topology.

The result of executing the EntryProcessor is returned as a Map of EntryProcessorResults, one result per key. Should the EntryProcessor or Caching implementation throw an exception, the exception is wrapped and re-thrown when a call to EntryProcessorResult.get() is made.

Parameters:

keys - the set of keys for entries to process

entryProcessor - the EntryProcessor to invoke

arguments - additional arguments to pass to the EntryProcessor

Returns:

the map of EntryProcessorResults of the processing per key, if any, defined by the EntryProcessor implementation. No mappings will be returned for EntryProcessors that return a null value for a key.

Throws:

NullPointerException - if keys or EntryProcessor are null

IllegalStateException - if the cache is isClosed()

ClassCastException - if the implementation is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for the Cache

See Also:

EntryProcessor

getName

String getName()

Return the name of the cache.

Returns:

the name of the cache.

getCacheManager

CacheManager getCacheManager()

Gets the CacheManager that owns and manages the Cache.

Returns:

the manager or null if the Cache is not managed

close

void close()

Closing a Cache signals to the CacheManager that produced or owns the Cache that it should no longer be managed. At this point in time the CacheManager:

• must close and release all resources being coordinated on behalf of the Cache by the CacheManager. This includes calling the close method on configured CacheLoader, CacheWriter, registered CacheEntryListeners and ExpiryPolicy instances that implement the java.io.Closeable interface.
• prevent events being delivered to configured CacheEntryListeners registered on the Cache
• not return the name of the Cache when the CacheManager getCacheNames() method is called

Once closed any attempt to use an operational method on a Cache will throw an IllegalStateException.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

SecurityException - when the operation could not be performed due to the current security settings

isClosed

boolean isClosed()

Determines whether this Cache instance has been closed. A Cache is considered closed if;

1. the close() method has been called
2. the associated getCacheManager() has been closed, or
3. the Cache has been removed from the associated getCacheManager()

This method generally cannot be called to determine whether a Cache instance is valid or invalid. A typical client can determine that a Cache is invalid by catching any exceptions that might be thrown when an operation is attempted.

Returns:

true if this Cache instance is closed; false if it is still open

unwrap

<T> T unwrap(Class<T> clazz)

Provides a standard way to access the underlying concrete caching implementation to provide access to further, proprietary features.

If the provider's implementation does not support the specified class, the IllegalArgumentException is thrown.

Parameters:

clazz - the proprietary class or interface of the underlying concrete cache. It is this type that is returned.

Returns:

an instance of the underlying concrete cache

Throws:

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

SecurityException - when the operation could not be performed due to the current security settings

registerCacheEntryListener

void registerCacheEntryListener(CacheEntryListenerConfiguration<K,V> cacheEntryListenerConfiguration)

Registers a CacheEntryListener. The supplied CacheEntryListenerConfiguration is used to instantiate a listener and apply it to those events specified in the configuration.

Parameters:

cacheEntryListenerConfiguration - a factory and related configuration for creating the listener

Throws:

IllegalArgumentException - is the same CacheEntryListenerConfiguration is used more than once

IllegalStateException - if the cache is isClosed()

See Also:

CacheEntryListener

deregisterCacheEntryListener

void deregisterCacheEntryListener(CacheEntryListenerConfiguration<K,V> cacheEntryListenerConfiguration)

Deregisters a listener, using the CacheEntryListenerConfiguration that was used to register it.

Both listeners registered at configuration time, and those created at runtime with registerCacheEntryListener(javax.cache.configuration.CacheEntryListenerConfiguration<K, V>) can be deregistered.

Parameters:

cacheEntryListenerConfiguration - the factory and related configuration that was used to create the listener

Throws:

IllegalStateException - if the cache is isClosed()

iterator

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

The ordering of iteration over entries is undefined.

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

Iterator.next() may return null if the entry is no longer present, has expired or has been evicted.

Specified by:

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

Throws:

IllegalStateException - if the cache is isClosed()