JSR107 API and SPI 1.1.1 · javax.cache.Cache

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

Method Summary

Modifier and Type	Method and Description
public void	clear() Clears the contents of the cache, without notifying listeners or `CacheWriter`s.
public void	close() Redeclares java.io.Closeable.close. Closing a `Cache` signals to the `CacheManager` that produced or owns the `Cache` that it should no longer be managed.
public boolean	Returns: `true` if this map contains a mapping for the specified key containsKey(K key whose presence in this cache is to be tested. key) Determines if the `Cache` contains an entry for the specified key.
public void	deregisterCacheEntryListener(CacheEntryListenerConfiguration<K, V> the factory and related configuration that was used to create the listener cacheEntryListenerConfiguration) Deregisters a listener, using the `CacheEntryListenerConfiguration` that was used to register it.
public V	Returns: the element, or null, if it does not exist. get(K the key whose associated value is to be returned key) Gets an entry from the cache.
public Map<K, V>	Returns: A map of entries that were found for the given keys. Keys not found in the cache are not in the returned map. getAll(Set<? extends K> The keys whose associated values are to be returned. keys) Gets a collection of entries from the `Cache`, returning them as `Map` of the values associated with the set of keys requested.
public V	Returns: the value associated with the key at the start of the operation or null if none was associated getAndPut(K key with which the specified value is to be associated key, V value to be associated with the specified key value) Associates the specified value with the specified key in this cache, returning an existing value if one existed.
public V	Returns: the value if one existed or null if no mapping existed for this key getAndRemove(K key with which the specified value is associated key) Atomically removes the entry for a key only if currently mapped to some value.
public V	Returns: the previous value associated with the specified key, or `null` if there was no mapping for the key. getAndReplace(K key with which the specified value is associated key, V value to be associated with the specified key value) Atomically replaces the value for a given key if and only if there is a value currently mapped by the key.
public CacheManager	Returns: the manager or `null` if the `Cache` is not managed getCacheManager() Gets the `CacheManager` that owns and manages the `Cache`.
public < the type of the Configuration C extends Configuration<K, V>> C	Returns: the requested implementation of `Configuration` getConfiguration(Class<C> the configuration interface or class to return. This includes `Configuration`.class and `javax.cache.configuration.CompleteConfiguration`s. clazz) Provides a standard way to access the configuration of a cache using JCache configuration or additional proprietary configuration.
public String	Returns: the name of the cache. getName() Return the name of the cache.
public < the type of the return value T> T	Returns: the result of the processing, if any, defined by the `EntryProcessor` implementation invoke(K the key to the entry key, EntryProcessor<K, V, T> the `EntryProcessor` to invoke entryProcessor, Object... additional arguments to pass to the `EntryProcessor` arguments) Invokes an `EntryProcessor` against the `Entry` specified by the provided key.
public < the type of the return value T> Map<K, EntryProcessorResult<T>>	Returns: the map of `EntryProcessorResult`s of the processing per key, if any, defined by the `EntryProcessor` implementation. No mappings will be returned for `EntryProcessor`s that return a `null` value for a key. invokeAll(Set<? extends K> the set of keys for entries to process keys, EntryProcessor<K, V, T> the `EntryProcessor` to invoke entryProcessor, Object... additional arguments to pass to the `EntryProcessor` arguments) Invokes an `EntryProcessor` against the set of `Entry`s specified by the set of keys.
public boolean	Returns: true if this Cache instance is closed; false if it is still open isClosed() Determines whether this Cache instance has been closed.
public Iterator<Cache.Entry<K, V>>	iterator() Redeclares java.lang.Iterable.iterator. Returns an iterator over elements of type `T`.
public void	loadAll(Set<? extends K> the keys to load keys, boolean when true existing values in the Cache will be replaced by those loaded from a CacheLoader replaceExistingValues, CompletionListener the CompletionListener (may be null) completionListener) Asynchronously loads the specified entries into the cache using the configured `CacheLoader` for the given keys.
public void	put(K key with which the specified value is to be associated key, V value to be associated with the specified key value) Associates the specified value with the specified key in the cache.
public void	putAll(Map<? extends K, ? extends V> mappings to be stored in this cache map) Copies all of the entries from the specified map to the `Cache`.
public boolean	Returns: true if a value was set. putIfAbsent(K key with which the specified value is to be associated key, V value to be associated with the specified key value) Atomically associates the specified key with the given value if it is not already associated with a value.
public void	registerCacheEntryListener(CacheEntryListenerConfiguration<K, V> a factory and related configuration for creating the listener cacheEntryListenerConfiguration) Registers a `CacheEntryListener`.
public boolean	Returns: returns false if there was no matching key remove(K key whose mapping is to be removed from the cache key) Removes the mapping for a key from this cache if it is present.
public boolean	Returns: returns false if there was no matching key remove(K key whose mapping is to be removed from the cache key, V value expected to be associated with the specified key oldValue) Atomically removes the mapping for a key only if currently mapped to the given value.
public void	removeAll(Set<? extends K> the keys to remove keys) Removes entries for the specified keys.
public void	removeAll() Removes all of the mappings from this cache.
public boolean	Returns: `true` if the value was replaced replace(K key with which the specified value is associated key, V value expected to be associated with the specified key oldValue, V value to be associated with the specified key newValue) Atomically replaces the entry for a key only if currently mapped to a given value.
public boolean	Returns: `true` if the value was replaced replace(K the key with which the specified value is associated key, V the value to be associated with the specified key value) Atomically replaces the entry for a key only if currently mapped to some value.
public < the type of the underlying `Cache` implementation T> T	Returns: an instance of the underlying concrete cache unwrap(Class<T> the proprietary class or interface of the underlying concrete cache. It is this type that is returned. clazz) Provides a standard way to access the underlying concrete caching implementation to provide access to further, proprietary features.

Inherited from java.lang.Iterable:: forEach spliterator

Method Detail

clear back to summary

clear	back to summary
public void clear() Clears the contents of the cache, without notifying listeners or `CacheWriter`s. Exceptions IllegalStateException: if the cache is `isClosed()` CacheException: if there is a problem during the clear

public void clear()

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

Exceptions

IllegalStateException:: if the cache is isClosed()
CacheException:: if there is a problem during the clear

close back to summary

close	back to summary
public void close() Redeclares java.io.Closeable.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 `CacheEntryListener`s and `ExpiryPolicy` instances that implement the java.io.Closeable interface. prevent events being delivered to configured `CacheEntryListener`s 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`. Closing a Cache does not necessarily destroy the contents of a Cache. It simply signals to the owning CacheManager that the Cache is no longer required by the application and that future uses of a specific Cache instance should not be permitted. Depending on the implementation and Cache topology, (e.g. a storage-backed or distributed cache), the contents of a closed Cache may still be available and accessible by other applications, or, in fact, via the Cache Manager that previously owned the Cache, if an application calls getCache at some point in the future. Exceptions SecurityException: when the operation could not be performed due to the current security settings

public void close()

Redeclares java.io.Closeable.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.

Closing a Cache does not necessarily destroy the contents of a Cache. It simply signals to the owning CacheManager that the Cache is no longer required by the application and that future uses of a specific Cache instance should not be permitted.

Depending on the implementation and Cache topology, (e.g. a storage-backed or distributed cache), the contents of a closed Cache may still be available and accessible by other applications, or, in fact, via the Cache Manager that previously owned the Cache, if an application calls getCache at some point in the future.

Exceptions

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

containsKey back to summary

containsKey	back to summary
public 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.) If the cache is configured read-through the associated `CacheLoader` is not called. Only the cache is checked. Parameters key:K key whose presence in this cache is to be tested. Returns:boolean `true` if this map contains a mapping for the specified key Exceptions 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 `java.util.Map#containsKey(Object)`

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

If the cache is configured read-through the associated CacheLoader is not called. Only the cache is checked.

Parameters

key:K: key whose presence in this cache is to be tested.

Returns:boolean

true if this map contains a mapping for the specified key

Exceptions

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

java.util.Map#containsKey(Object)

deregisterCacheEntryListener back to summary

deregisterCacheEntryListener	back to summary
public 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` can be deregistered. Parameters cacheEntryListenerConfiguration:CacheEntryListenerConfiguration<K, V> the factory and related configuration that was used to create the listener Exceptions IllegalStateException: if the cache is `isClosed()`

public 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 can be deregistered.

Parameters

cacheEntryListenerConfiguration:CacheEntryListenerConfiguration<K, V>: the factory and related configuration that was used to create the listener

Exceptions

IllegalStateException:: if the cache is isClosed()

get back to summary

get	back to summary
public 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:K the key whose associated value is to be returned Returns:V the element, or null, if it does not exist. Exceptions 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`

public 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:K: the key whose associated value is to be returned

Returns:V

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

Exceptions

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 back to summary

getAll	back to summary
public 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:Set<? extends K> The keys whose associated values are to be returned. Returns:Map<K, V> A map of entries that were found for the given keys. Keys not found in the cache are not in the returned map. Exceptions 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`

public 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:Set<? extends K>: The keys whose associated values are to be returned.

Returns:Map<K, V>

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

Exceptions

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

getAndPut back to summary

getAndPut	back to summary
public 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. If the cache is configured write-through the associated `CacheWriter#write(Cache.Entry)` method will be called. Parameters key:K key with which the specified value is to be associated value:V value to be associated with the specified key Returns:V the value associated with the key at the start of the operation or null if none was associated Exceptions 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(Cache.Entry)`

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

If the cache is configured write-through the associated CacheWriter#write(Cache.Entry) method will be called.

Parameters

key:K: key with which the specified value is to be associated
value:V: value to be associated with the specified key

Returns:V

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

Exceptions

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

getAndRemove back to summary

getAndRemove	back to summary
public 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. If the cache is configured write-through the associated `CacheWriter#delete(Object)` method will be called. Parameters key:K key with which the specified value is associated Returns:V the value if one existed or null if no mapping existed for this key Exceptions 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`

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

If the cache is configured write-through the associated CacheWriter#delete(Object) method will be called.

Parameters

key:K: key with which the specified value is associated

Returns:V

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

Exceptions

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

getAndReplace back to summary

getAndReplace	back to summary
public 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. If the cache is configured write-through, and this method returns true, the associated `CacheWriter#write(Cache.Entry)` method will be called. Parameters key:K key with which the specified value is associated value:V value to be associated with the specified key Returns:V the previous value associated with the specified key, or `null` if there was no mapping for the key. Exceptions 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 `java.util.concurrent.ConcurrentMap#replace(Object, Object)`, `CacheWriter#write`

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

If the cache is configured write-through, and this method returns true, the associated CacheWriter#write(Cache.Entry) method will be called.

Parameters

key:K: key with which the specified value is associated
value:V: value to be associated with the specified key

Returns:V

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

Exceptions

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

getCacheManager back to summary

getCacheManager	back to summary
public CacheManager getCacheManager() Gets the `CacheManager` that owns and manages the `Cache`. Returns:CacheManager the manager or `null` if the `Cache` is not managed

public CacheManager getCacheManager()

Gets the CacheManager that owns and manages the Cache.

Returns:CacheManager: the manager or null if the Cache is not managed

getConfiguration back to summary

getConfiguration	back to summary
public <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 <C> the type of the Configuration clazz:Class<C> the configuration interface or class to return. This includes `Configuration`.class and `javax.cache.configuration.CompleteConfiguration`s. Returns:C the requested implementation of `Configuration` Exceptions IllegalArgumentException: if the caching provider doesn't support the specified class.

public <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

<C>: the type of the Configuration
clazz:Class<C>: the configuration interface or class to return. This includes Configuration.class and javax.cache.configuration.CompleteConfigurations.

Returns:C

the requested implementation of Configuration

Exceptions

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

getName	back to summary
public String getName() Return the name of the cache. Returns:String the name of the cache.

getName

back to summary

public String getName()

Return the name of the cache.

Returns:String: the name of the cache.

invoke back to summary

invoke	back to summary
public <T> T invoke(K key, EntryProcessor<K, V, T> entryProcessor, Object... arguments) throws EntryProcessorException Invokes an `EntryProcessor` against the `Entry` specified by the provided key. Parameters <T> the type of the return value key:K the key to the entry entryProcessor:EntryProcessor<K, V, T> the `EntryProcessor` to invoke arguments:Object[] additional arguments to pass to the `EntryProcessor` Returns:T the result of the processing, if any, defined by the `EntryProcessor` implementation Exceptions EntryProcessorException: if an exception is thrown by the `EntryProcessor`, a Caching Implementation must wrap any `Exception` thrown wrapped in an `EntryProcessorException`. 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` See Also `EntryProcessor`

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

Invokes an EntryProcessor against the Entry specified by the provided key.

Parameters

<T>: the type of the return value
key:K: the key to the entry
entryProcessor:EntryProcessor<K, V, T>: the EntryProcessor to invoke
arguments:Object[]: additional arguments to pass to the EntryProcessor

Returns:T

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

Exceptions

EntryProcessorException:: if an exception is thrown by the EntryProcessor, a Caching Implementation must wrap any Exception thrown wrapped in an EntryProcessorException.
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

See Also

EntryProcessor

invokeAll back to summary

invokeAll	back to summary
public <T> Map<K, EntryProcessorResult<T>> invokeAll(Set<? extends K> keys, EntryProcessor<K, V, T> entryProcessor, Object... arguments) Invokes an `EntryProcessor` against the set of `Entry`s specified by the set of keys. 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 `EntryProcessorResult`s, one result per key. Should the `EntryProcessor` or Caching implementation throw an exception, the exception is wrapped and re-thrown when a call to `javax.cache.processor.EntryProcessorResult#get()` is made. Parameters <T> the type of the return value keys:Set<? extends K> the set of keys for entries to process entryProcessor:EntryProcessor<K, V, T> the `EntryProcessor` to invoke arguments:Object[] additional arguments to pass to the `EntryProcessor` Returns:Map<K, EntryProcessorResult<T>> the map of `EntryProcessorResult`s of the processing per key, if any, defined by the `EntryProcessor` implementation. No mappings will be returned for `EntryProcessor`s that return a `null` value for a key. Exceptions 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`

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

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

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 javax.cache.processor.EntryProcessorResult#get() is made.

Parameters

<T>: the type of the return value
keys:Set<? extends K>: the set of keys for entries to process
entryProcessor:EntryProcessor<K, V, T>: the EntryProcessor to invoke
arguments:Object[]: additional arguments to pass to the EntryProcessor

Returns:Map<K, EntryProcessorResult<T>>

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.

Exceptions

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

isClosed back to summary

isClosed	back to summary
public boolean isClosed() Determines whether this Cache instance has been closed. A Cache is considered closed if; the `close()` method has been called the associated `getCacheManager()` has been closed, or 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:boolean true if this Cache instance is closed; false if it is still open

public boolean isClosed()

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

the close() method has been called
the associated getCacheManager() has been closed, or
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:boolean: true if this Cache instance is closed; false if it is still open

iterator back to summary

iterator	back to summary
public Iterator<Cache.Entry<K, V>> iterator() Redeclares java.lang.Iterable.iterator. Doc from java.lang.Iterable.iterator. Returns an iterator over elements of type `T`. The ordering of iteration over entries is undefined. During iteration, any entries that are removed will have their appropriate CacheEntryRemovedListeners notified. When iterating over a cache it must be assumed that the underlying cache may be changing, with entries being added, removed, evicted and expiring. `java.util.Iterator#next()` may therefore return null. Returns:Iterator<Cache.Entry<K, V>> an Iterator. Exceptions IllegalStateException: if the cache is `isClosed()`

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

Redeclares java.lang.Iterable.iterator.

Doc from java.lang.Iterable.iterator.

Returns an iterator over elements of type T.

The ordering of iteration over entries is undefined.

During iteration, any entries that are removed will have their appropriate CacheEntryRemovedListeners notified.

When iterating over a cache it must be assumed that the underlying cache may be changing, with entries being added, removed, evicted and expiring. java.util.Iterator#next() may therefore return null.

Returns:Iterator<Cache.Entry<K, V>>

an Iterator.

Exceptions

IllegalStateException:: if the cache is isClosed()

loadAll back to summary

loadAll	back to summary
public 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 `Set`s 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:Set<? extends K> the keys to load replaceExistingValues:boolean when true existing values in the Cache will be replaced by those loaded from a CacheLoader completionListener:CompletionListener the CompletionListener (may be null) Exceptions 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`

public 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:Set<? extends K>: the keys to load
replaceExistingValues:boolean: when true existing values in the Cache will be replaced by those loaded from a CacheLoader
completionListener:CompletionListener: the CompletionListener (may be null)

Exceptions

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 back to summary

put	back to summary
public 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`.) If the cache is configured write-through the `CacheWriter#write(Cache.Entry)` method will be called. Parameters key:K key with which the specified value is to be associated value:V value to be associated with the specified key Exceptions 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 `java.util.Map#put(Object, Object)`, `getAndPut(Object, Object)`, `getAndReplace(Object, Object)`, `CacheWriter#write`

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

If the cache is configured write-through the CacheWriter#write(Cache.Entry) method will be called.

Parameters

key:K: key with which the specified value is to be associated
value:V: value to be associated with the specified key

Exceptions

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

putAll back to summary

putAll	back to summary
public 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. If the cache is configured write-through the associated `CacheWriter#writeAll` method will be called. Parameters map:Map<? extends K, ? extends V> mappings to be stored in this cache Exceptions 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`

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

If the cache is configured write-through the associated CacheWriter#writeAll method will be called.

Parameters

map:Map<? extends K, ? extends V>: mappings to be stored in this cache

Exceptions

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

putIfAbsent back to summary

putIfAbsent	back to summary
public 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. If the cache is configured write-through, and this method returns true, the associated `CacheWriter#write(Cache.Entry)` method will be called. Parameters key:K key with which the specified value is to be associated value:V value to be associated with the specified key Returns:boolean true if a value was set. Exceptions 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`

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

If the cache is configured write-through, and this method returns true, the associated CacheWriter#write(Cache.Entry) method will be called.

Parameters

key:K: key with which the specified value is to be associated
value:V: value to be associated with the specified key

Returns:boolean

true if a value was set.

Exceptions

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

registerCacheEntryListener back to summary

registerCacheEntryListener	back to summary
public 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:CacheEntryListenerConfiguration<K, V> a factory and related configuration for creating the listener Exceptions IllegalArgumentException: is the same CacheEntryListenerConfiguration is used more than once IllegalStateException: if the cache is `isClosed()` See Also `CacheEntryListener`

public 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:CacheEntryListenerConfiguration<K, V>: a factory and related configuration for creating the listener

Exceptions

IllegalArgumentException:: is the same CacheEntryListenerConfiguration is used more than once
IllegalStateException:: if the cache is isClosed()

See Also

CacheEntryListener

remove back to summary

remove	back to summary
public 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. If the cache is configured write-through the associated `CacheWriter#delete(Object)` method will be called. Parameters key:K key whose mapping is to be removed from the cache Returns:boolean returns false if there was no matching key Exceptions 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`

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

If the cache is configured write-through the associated CacheWriter#delete(Object) method will be called.

Parameters

key:K: key whose mapping is to be removed from the cache

Returns:boolean

returns false if there was no matching key

Exceptions

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

remove back to summary

remove	back to summary
public 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. If the cache is configured write-through, and this method returns true, the associated `CacheWriter#delete(Object)` method will be called. Parameters key:K key whose mapping is to be removed from the cache oldValue:V value expected to be associated with the specified key Returns:boolean returns false if there was no matching key Exceptions 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`

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

If the cache is configured write-through, and this method returns true, the associated CacheWriter#delete(Object) method will be called.

Parameters

key:K: key whose mapping is to be removed from the cache
oldValue:V: value expected to be associated with the specified key

Returns:boolean

returns false if there was no matching key

Exceptions

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

removeAll back to summary

removeAll	back to summary
public 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 `CacheEntryRemovedListener`s if the cache is a write-through cache, the `CacheWriter` Parameters keys:Set<? extends K> the keys to remove Exceptions 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`

public 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

Parameters

keys:Set<? extends K>: the keys to remove

Exceptions

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

removeAll back to summary

removeAll	back to summary
public 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 `CacheEntryRemovedListener`s 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. Exceptions IllegalStateException: if the cache is `isClosed()` CacheException: if there is a problem during the remove See Also `clear()`, `CacheWriter#deleteAll`

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

Exceptions

IllegalStateException:: if the cache is isClosed()
CacheException:: if there is a problem during the remove

See Also

clear(), CacheWriter#deleteAll

replace back to summary

replace	back to summary
public 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. If the cache is configured write-through, and this method returns true, the associated `CacheWriter#write(Cache.Entry)` method will be called. Parameters key:K key with which the specified value is associated oldValue:V value expected to be associated with the specified key newValue:V value to be associated with the specified key Returns:boolean `true` if the value was replaced Exceptions 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`

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

If the cache is configured write-through, and this method returns true, the associated CacheWriter#write(Cache.Entry) method will be called.

Parameters

key:K: key with which the specified value is associated
oldValue:V: value expected to be associated with the specified key
newValue:V: value to be associated with the specified key

Returns:boolean

true if the value was replaced

Exceptions

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

replace back to summary

replace	back to summary
public 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. If the cache is configured write-through, and this method returns true, the associated `CacheWriter#write(Cache.Entry)` method will be called. Parameters key:K the key with which the specified value is associated value:V the value to be associated with the specified key Returns:boolean `true` if the value was replaced Exceptions 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`

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

If the cache is configured write-through, and this method returns true, the associated CacheWriter#write(Cache.Entry) method will be called.

Parameters

key:K: the key with which the specified value is associated
value:V: the value to be associated with the specified key

Returns:boolean

true if the value was replaced

Exceptions

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

unwrap back to summary

unwrap	back to summary
public <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 <T> the type of the underlying `Cache` implementation clazz:Class<T> the proprietary class or interface of the underlying concrete cache. It is this type that is returned. Returns:T an instance of the underlying concrete cache Exceptions 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

public <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

<T>: the type of the underlying Cache implementation
clazz:Class<T>: the proprietary class or interface of the underlying concrete cache. It is this type that is returned.

Returns:T

an instance of the underlying concrete cache

Exceptions

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

Modifier and Type	Method and Description
public K	Returns: the key corresponding to this entry getKey() Returns the key corresponding to this entry.
public V	Returns: the value corresponding to this entry getValue() Returns the value stored in the cache when this entry was created.
public < the type of the underlying `Entry` implementation T> T	Returns: an instance of the underlying concrete cache unwrap(Class<T> the proprietary class or interface of the underlying concrete cache. It is this type that is returned. clazz) Provides a standard way to access the underlying concrete cache entry implementation in order to provide access to further, proprietary features.

public Interface Cache<K, V>

Nested and Inner Type Summary

Method Summary

Method Detail

public Interface Cache.Entry<K, V>

Method Summary

Method Detail