org.infinispan
Class DecoratedCache<K,V>

java.lang.Object
  org.infinispan.AbstractDelegatingCache<K,V>
      org.infinispan.AbstractDelegatingAdvancedCache<K,V>
          org.infinispan.DecoratedCache<K,V>

All Implemented Interfaces:

ConcurrentMap<K,V>, Map<K,V>, AdvancedCache<K,V>, BasicCache<K,V>, Cache<K,V>, Lifecycle, Listenable

public class DecoratedCache<K,V>
extends AbstractDelegatingAdvancedCache<K,V>

A decorator to a cache, which can be built with a specific ClassLoader and a set of Flags. This ClassLoader and set of Flags will be applied to all cache invocations made via this decorator.

In addition to cleaner and more readable code, this approach offers a performance benefit to using AdvancedCache.with(ClassLoader) or AdvancedCache.withFlags(org.infinispan.context.Flag...) APIs, thanks to internal optimizations that can be made when the ClassLoader and Flag set is unchanging.

Since:

5.1

Author:

Manik Surtani, Sanne Grinovero

See Also:

AdvancedCache.with(ClassLoader), AdvancedCache.withFlags(org.infinispan.context.Flag...)

Nested Class Summary

Nested classes/interfaces inherited from class org.infinispan.AbstractDelegatingAdvancedCache

AbstractDelegatingAdvancedCache.AdvancedCacheWrapper<K,V>

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Field Summary

Fields inherited from class org.infinispan.AbstractDelegatingAdvancedCache

cache

Constructor Summary

DecoratedCache(AdvancedCache<K,V> delegate, ClassLoader classLoader)

DecoratedCache(AdvancedCache<K,V> delegate, ClassLoader classLoader, Flag... flags)

DecoratedCache(AdvancedCache<K,V> delegate, Flag... flags)

Method Summary

void	addListener(Object listener) Adds a listener to the component.
void	clear()
NotifyingFuture<Void>	clearAsync() Asynchronous version of Map.clear().
boolean	containsKey(Object key)
Set<Map.Entry<K,V>>	entrySet() Returns a set view of the mappings contained in this cache.
void	evict(K key) Evicts an entry from the memory of the cache.
V	get(Object key)
NotifyingFuture<V>	getAsync(K key) Asynchronous version of Map.get(Object) that allows user code to retrieve the value associated with a key at a later stage, hence allowing multiple parallel get requests to be sent.
CacheEntry	getCacheEntry(K key) Retrieves a CacheEntry corresponding to a specific key.
ClassLoader	getClassLoader() Returns the cache loader associated associated with this cache.
EnumSet<Flag>	getFlags()
boolean	isEmpty()
Set<K>	keySet() Returns a set view of the keys contained in this cache.
boolean	lock(Collection<? extends K> keys) Locks collections of keys eagerly across cache nodes in a cluster.
boolean	lock(K... keys) Locks a given key or keys eagerly across cache nodes in a cluster.
V	put(K key, V value) If the return value of this operation will be ignored by the application, the user is strongly encouraged to use the Flag.IGNORE_RETURN_VALUES flag when invoking this method in order to make it behave as efficiently as possible (i.e.
V	put(K key, V value, long lifespan, TimeUnit unit) An overloaded form of BasicCache.put(Object, Object), which takes in lifespan parameters.
V	put(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit) An overloaded form of BasicCache.put(Object, Object), which takes in lifespan parameters.
V	put(K key, V value, Metadata metadata) An overloaded form of #put(K, V), which takes in an instance of Metadata which can be used to provide metadata information for the entry being stored, such as lifespan, version of value...etc.
void	putAll(Map<? extends K,? extends V> m)
void	putAll(Map<? extends K,? extends V> map, long lifespan, TimeUnit unit) An overloaded form of Map.putAll(Map), which takes in lifespan parameters.
void	putAll(Map<? extends K,? extends V> map, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit) An overloaded form of Map.putAll(Map), which takes in lifespan parameters.
NotifyingFuture<Void>	putAllAsync(Map<? extends K,? extends V> data) Asynchronous version of Map.putAll(Map).
NotifyingFuture<Void>	putAllAsync(Map<? extends K,? extends V> data, long lifespan, TimeUnit unit) Asynchronous version of BasicCache.putAll(Map, long, TimeUnit).
NotifyingFuture<Void>	putAllAsync(Map<? extends K,? extends V> data, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version of BasicCache.putAll(Map, long, TimeUnit, long, TimeUnit).
NotifyingFuture<V>	putAsync(K key, V value) Asynchronous version of BasicCache.put(Object, Object).
NotifyingFuture<V>	putAsync(K key, V value, long lifespan, TimeUnit unit) Asynchronous version of BasicCache.put(Object, Object, long, TimeUnit) .
NotifyingFuture<V>	putAsync(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version of BasicCache.put(Object, Object, long, TimeUnit, long, TimeUnit).
NotifyingFuture<V>	putAsync(K key, V value, Metadata metadata) Asynchronous version of AdvancedCache.put(Object, Object, Metadata) which stores metadata alongside the value.
void	putForExternalRead(K key, V value) Under special operating behavior, associates the value with the specified key.
V	putIfAbsent(K key, V value)
V	putIfAbsent(K key, V value, long lifespan, TimeUnit unit) An overloaded form of ConcurrentMap.putIfAbsent(Object, Object), which takes in lifespan parameters.
V	putIfAbsent(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit) An overloaded form of ConcurrentMap.putIfAbsent(Object, Object), which takes in lifespan parameters.
V	putIfAbsent(K key, V value, Metadata metadata) An overloaded form of #putIfAbsent(K, V), which takes in an instance of Metadata which can be used to provide metadata information for the entry being stored, such as lifespan, version of value...etc.
NotifyingFuture<V>	putIfAbsentAsync(K key, V value) Asynchronous version of ConcurrentMap.putIfAbsent(Object, Object).
NotifyingFuture<V>	putIfAbsentAsync(K key, V value, long lifespan, TimeUnit unit) Asynchronous version of BasicCache.putIfAbsent(Object, Object, long, TimeUnit) .
NotifyingFuture<V>	putIfAbsentAsync(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version of BasicCache.putIfAbsent(Object, Object, long, TimeUnit, long, TimeUnit).
V	remove(Object key) If the return value of this operation will be ignored by the application, the user is strongly encouraged to use the Flag.IGNORE_RETURN_VALUES flag when invoking this method in order to make it behave as efficiently as possible (i.e.
boolean	remove(Object key, Object value)
NotifyingFuture<V>	removeAsync(Object key) Asynchronous version of BasicCache.remove(Object).
NotifyingFuture<Boolean>	removeAsync(Object key, Object value) Asynchronous version of ConcurrentMap.remove(Object, Object).
V	replace(K key, V value)
V	replace(K key, V value, long lifespan, TimeUnit unit) An overloaded form of ConcurrentMap.replace(Object, Object), which takes in lifespan parameters.
V	replace(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit) An overloaded form of ConcurrentMap.replace(Object, Object), which takes in lifespan parameters.
V	replace(K key, V value, Metadata metadata) An overloaded form of #replace(K, V), which takes in an instance of Metadata which can be used to provide metadata information for the entry being stored, such as lifespan, version of value...etc.
boolean	replace(K key, V oldValue, V newValue)
boolean	replace(K key, V oldValue, V value, long lifespan, TimeUnit unit) An overloaded form of ConcurrentMap.replace(Object, Object, Object), which takes in lifespan parameters.
boolean	replace(K key, V oldValue, V value, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit) An overloaded form of ConcurrentMap.replace(Object, Object, Object), which takes in lifespan parameters.
boolean	replace(K key, V oldValue, V value, Metadata metadata) An overloaded form of #replace(K, V, V), which takes in an instance of Metadata which can be used to provide metadata information for the entry being stored, such as lifespan, version of value...etc.
NotifyingFuture<V>	replaceAsync(K key, V value) Asynchronous version of ConcurrentMap.replace(Object, Object).
NotifyingFuture<V>	replaceAsync(K key, V value, long lifespan, TimeUnit unit) Asynchronous version of BasicCache.replace(Object, Object, long, TimeUnit).
NotifyingFuture<V>	replaceAsync(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version of BasicCache.replace(Object, Object, long, TimeUnit, long, TimeUnit).
NotifyingFuture<Boolean>	replaceAsync(K key, V oldValue, V newValue) Asynchronous version of ConcurrentMap.replace(Object, Object, Object).
NotifyingFuture<Boolean>	replaceAsync(K key, V oldValue, V newValue, long lifespan, TimeUnit unit) Asynchronous version of BasicCache.replace(Object, Object, Object, long, TimeUnit).
NotifyingFuture<Boolean>	replaceAsync(K key, V oldValue, V newValue, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version of BasicCache.replace(Object, Object, Object, long, TimeUnit, long, TimeUnit).
int	size()
void	stop()
Collection<V>	values() Returns a collection view of the values contained in this cache.
AdvancedCache<K,V>	with(ClassLoader classLoader) Using this operation, users can call any AdvancedCache operation with a given ClassLoader.
AdvancedCache<K,V>	withFlags(Flag... flags) A method that adds flags to any API call.

Methods inherited from class org.infinispan.AbstractDelegatingAdvancedCache

addInterceptor, addInterceptorAfter, addInterceptorBefore, applyDelta, getAdvancedCache, getBatchContainer, getCacheEntry, getComponentRegistry, getDataContainer, getDistributionManager, getEvictionManager, getInterceptorChain, getInvocationContextContainer, getLockManager, getRpcManager, getStats, getTransactionManager, getXAResource, putForExternalRead, removeInterceptor, removeInterceptor

Methods inherited from class org.infinispan.AbstractDelegatingCache

compact, containsValue, endBatch, getCacheConfiguration, getCacheManager, getConfiguration, getDelegate, getListeners, getName, getStatus, getVersion, removeListener, set, start, startBatch, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.infinispan.Cache

compact, endBatch, getCacheConfiguration, getCacheManager, getConfiguration, getStatus, startBatch

Methods inherited from interface org.infinispan.api.BasicCache

getName, getVersion

Methods inherited from interface java.util.Map

containsValue, equals, hashCode

Methods inherited from interface org.infinispan.lifecycle.Lifecycle

start

Methods inherited from interface org.infinispan.notifications.Listenable

getListeners, removeListener

Constructor Detail

DecoratedCache

public DecoratedCache(AdvancedCache<K,V> delegate,
                      ClassLoader classLoader)

DecoratedCache

public DecoratedCache(AdvancedCache<K,V> delegate,
                      Flag... flags)

DecoratedCache

public DecoratedCache(AdvancedCache<K,V> delegate,
                      ClassLoader classLoader,
                      Flag... flags)

Method Detail

with

public AdvancedCache<K,V> with(ClassLoader classLoader)

Description copied from interface: AdvancedCache

Using this operation, users can call any AdvancedCache operation with a given ClassLoader. This means that any ClassLoader happening as a result of the cache operation will be done using the ClassLoader given. For example:

When users store POJO instances in caches configured with Configuration.storeAsBinary, these instances are transformed into byte arrays. When these entries are read from the cache, a lazy unmarshalling process happens where these byte arrays are transformed back into POJO instances. Using AdvancedCache.with(ClassLoader) when reading that enables users to provide the class loader that should be used when trying to locate the classes that are constructed as a result of the unmarshalling process.

    cache.with(classLoader).get(key);
 

Note that for the flag to take effect, the cache operation must be invoked on the instance returned by this method.

As an alternative to setting this on every invocation, users could also consider using the DecoratedCache wrapper, as this allows for more readable code. E.g.:

    Cache classLoaderSpecificCache = new DecoratedCache(cache, classLoader);
    classLoaderSpecificCache.get(key1);
    classLoaderSpecificCache.get(key2);
    classLoaderSpecificCache.get(key3);
 

Specified by:

with in interface AdvancedCache<K,V>

Overrides:

with in class AbstractDelegatingAdvancedCache<K,V>

Returns:

an AdvancedCache instance upon which operations can be called with a particular ClassLoader.

withFlags

public AdvancedCache<K,V> withFlags(Flag... flags)

Description copied from interface: AdvancedCache

A method that adds flags to any API call. For example, consider the following code snippet:

   cache.withFlags(Flag.FORCE_WRITE_LOCK).get(key);
 

will invoke a cache.get() with a write lock forced.

Note that for the flag to take effect, the cache operation must be invoked on the instance returned by this method.

As an alternative to setting this on every invocation, users could also consider using the DecoratedCache wrapper, as this allows for more readable code. E.g.:

    Cache forceWriteLockCache = new DecoratedCache(cache, Flag.FORCE_WRITE_LOCK);
    forceWriteLockCache.get(key1);
    forceWriteLockCache.get(key2);
    forceWriteLockCache.get(key3);
 

Specified by:

withFlags in interface AdvancedCache<K,V>

Overrides:

withFlags in class AbstractDelegatingAdvancedCache<K,V>

Parameters:

flags - a set of flags to apply. See the Flag documentation.

Returns:

an AdvancedCache instance on which a real operation is to be invoked, if the flags are to be applied.

getClassLoader

public ClassLoader getClassLoader()

Description copied from interface: AdvancedCache

Returns the cache loader associated associated with this cache. As an alternative to setting this on every invocation, users could also consider using the DecoratedCache wrapper.

Specified by:

getClassLoader in interface AdvancedCache<K,V>

Overrides:

getClassLoader in class AbstractDelegatingAdvancedCache<K,V>

Returns:

this cache's cache loader

stop

public void stop()

Specified by:

stop in interface Lifecycle

Overrides:

stop in class AbstractDelegatingCache<K,V>

lock

public boolean lock(K... keys)

Description copied from interface: AdvancedCache

Locks a given key or keys eagerly across cache nodes in a cluster.

Keys can be locked eagerly in the context of a transaction only.

Specified by:

lock in interface AdvancedCache<K,V>

Overrides:

lock in class AbstractDelegatingAdvancedCache<K,V>

Parameters:

keys - the keys to lock

Returns:

true if the lock acquisition attempt was successful for all keys; false will only be returned if the lock acquisition timed out and the operation has been called with Flag.FAIL_SILENTLY.

lock

public boolean lock(Collection<? extends K> keys)

Description copied from interface: AdvancedCache

Locks collections of keys eagerly across cache nodes in a cluster.

Collections of keys can be locked eagerly in the context of a transaction only.

Specified by:

lock in interface AdvancedCache<K,V>

Overrides:

lock in class AbstractDelegatingAdvancedCache<K,V>

Parameters:

keys - collection of keys to lock

Returns:

true if the lock acquisition attempt was successful for all keys; false will only be returned if the lock acquisition timed out and the operation has been called with Flag.FAIL_SILENTLY.

putForExternalRead

public void putForExternalRead(K key,
                               V value)

Description copied from interface: Cache

Under special operating behavior, associates the value with the specified key.

• Only goes through if the key specified does not exist; no-op otherwise (similar to ConcurrentMap.putIfAbsent(Object, Object))
• Force asynchronous mode for replication to prevent any blocking.
• invalidation does not take place.
• 0ms lock timeout to prevent any blocking here either. If the lock is not acquired, this method is a no-op, and swallows the timeout exception.
• Ongoing transactions are suspended before this call, so failures here will not affect any ongoing transactions.
• Errors and exceptions are 'silent' - logged at a much lower level than normal, and this method does not throw exceptions

This method is for caching data that has an external representation in storage, where, concurrent modification and transactions are not a consideration, and failure to put the data in the cache should be treated as a 'suboptimal outcome' rather than a 'failing outcome'.

An example of when this method is useful is when data is read from, for example, a legacy datastore, and is cached before returning the data to the caller. Subsequent calls would prefer to get the data from the cache and if the data doesn't exist in the cache, fetch again from the legacy datastore.

See JBCACHE-848 for details around this feature.

Specified by:

putForExternalRead in interface Cache<K,V>

Overrides:

putForExternalRead in class AbstractDelegatingCache<K,V>

Parameters:

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

value - value to be associated with the specified key.

evict

public void evict(K key)

Description copied from interface: Cache

Evicts an entry from the memory of the cache. Note that the entry is not removed from any configured cache stores or any other caches in the cluster (if used in a clustered mode). Use BasicCache.remove(Object) to remove an entry from the entire cache system.

This method is designed to evict an entry from memory to free up memory used by the application. This method uses a 0 lock acquisition timeout so it does not block in attempting to acquire locks. It behaves as a no-op if the lock on the entry cannot be acquired immediately.

Important: this method should not be called from within a transaction scope.

Specified by:

evict in interface Cache<K,V>

Overrides:

evict in class AbstractDelegatingCache<K,V>

Parameters:

key - key to evict

put

public V put(K key,
             V value,
             long lifespan,
             TimeUnit unit)

Description copied from interface: BasicCache

An overloaded form of BasicCache.put(Object, Object), which takes in lifespan parameters.

Specified by:

put in interface BasicCache<K,V>

Overrides:

put in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

unit - unit of measurement for the lifespan

Returns:

the value being replaced, or null if nothing is being replaced.

putIfAbsent

public V putIfAbsent(K key,
                     V value,
                     long lifespan,
                     TimeUnit unit)

Description copied from interface: BasicCache

An overloaded form of ConcurrentMap.putIfAbsent(Object, Object), which takes in lifespan parameters.

Specified by:

putIfAbsent in interface BasicCache<K,V>

Overrides:

putIfAbsent in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

unit - unit of measurement for the lifespan

Returns:

the value being replaced, or null if nothing is being replaced.

putAll

public void putAll(Map<? extends K,? extends V> map,
                   long lifespan,
                   TimeUnit unit)

Description copied from interface: BasicCache

An overloaded form of Map.putAll(Map), which takes in lifespan parameters. Note that the lifespan is applied to all mappings in the map passed in.

Specified by:

putAll in interface BasicCache<K,V>

Overrides:

putAll in class AbstractDelegatingCache<K,V>

Parameters:

map - map containing mappings to enter

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

unit - unit of measurement for the lifespan

replace

public V replace(K key,
                 V value,
                 long lifespan,
                 TimeUnit unit)

Description copied from interface: BasicCache

An overloaded form of ConcurrentMap.replace(Object, Object), which takes in lifespan parameters.

Specified by:

replace in interface BasicCache<K,V>

Overrides:

replace in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

unit - unit of measurement for the lifespan

Returns:

the value being replaced, or null if nothing is being replaced.

replace

public boolean replace(K key,
                       V oldValue,
                       V value,
                       long lifespan,
                       TimeUnit unit)

Description copied from interface: BasicCache

An overloaded form of ConcurrentMap.replace(Object, Object, Object), which takes in lifespan parameters.

Specified by:

replace in interface BasicCache<K,V>

Overrides:

replace in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

oldValue - value to replace

value - value to store

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

unit - unit of measurement for the lifespan

Returns:

true if the value was replaced, false otherwise

put

public V put(K key,
             V value,
             long lifespan,
             TimeUnit lifespanUnit,
             long maxIdleTime,
             TimeUnit maxIdleTimeUnit)

Description copied from interface: BasicCache

An overloaded form of BasicCache.put(Object, Object), which takes in lifespan parameters.

Specified by:

put in interface BasicCache<K,V>

Overrides:

put in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

lifespanUnit - time unit for lifespan

maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleTimeUnit - time unit for max idle time

Returns:

the value being replaced, or null if nothing is being replaced.

putIfAbsent

public V putIfAbsent(K key,
                     V value,
                     long lifespan,
                     TimeUnit lifespanUnit,
                     long maxIdleTime,
                     TimeUnit maxIdleTimeUnit)

Description copied from interface: BasicCache

An overloaded form of ConcurrentMap.putIfAbsent(Object, Object), which takes in lifespan parameters.

Specified by:

putIfAbsent in interface BasicCache<K,V>

Overrides:

putIfAbsent in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

lifespanUnit - time unit for lifespan

maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleTimeUnit - time unit for max idle time

Returns:

the value being replaced, or null if nothing is being replaced.

putAll

public void putAll(Map<? extends K,? extends V> map,
                   long lifespan,
                   TimeUnit lifespanUnit,
                   long maxIdleTime,
                   TimeUnit maxIdleTimeUnit)

Description copied from interface: BasicCache

An overloaded form of Map.putAll(Map), which takes in lifespan parameters. Note that the lifespan is applied to all mappings in the map passed in.

Specified by:

putAll in interface BasicCache<K,V>

Overrides:

putAll in class AbstractDelegatingCache<K,V>

Parameters:

map - map containing mappings to enter

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

lifespanUnit - time unit for lifespan

maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleTimeUnit - time unit for max idle time

replace

public V replace(K key,
                 V value,
                 long lifespan,
                 TimeUnit lifespanUnit,
                 long maxIdleTime,
                 TimeUnit maxIdleTimeUnit)

Description copied from interface: BasicCache

An overloaded form of ConcurrentMap.replace(Object, Object), which takes in lifespan parameters.

Specified by:

replace in interface BasicCache<K,V>

Overrides:

replace in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

lifespanUnit - time unit for lifespan

maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleTimeUnit - time unit for max idle time

Returns:

the value being replaced, or null if nothing is being replaced.

replace

public boolean replace(K key,
                       V oldValue,
                       V value,
                       long lifespan,
                       TimeUnit lifespanUnit,
                       long maxIdleTime,
                       TimeUnit maxIdleTimeUnit)

Description copied from interface: BasicCache

An overloaded form of ConcurrentMap.replace(Object, Object, Object), which takes in lifespan parameters.

Specified by:

replace in interface BasicCache<K,V>

Overrides:

replace in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

oldValue - value to replace

value - value to store

lifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.

lifespanUnit - time unit for lifespan

maxIdleTime - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleTimeUnit - time unit for max idle time

Returns:

true if the value was replaced, false otherwise

putAsync

public NotifyingFuture<V> putAsync(K key,
                                   V value)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.put(Object, Object). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.put(Object, Object) if used in LOCAL mode.

Specified by:

putAsync in interface BasicCache<K,V>

Overrides:

putAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

Returns:

a future containing the old value replaced.

putAsync

public NotifyingFuture<V> putAsync(K key,
                                   V value,
                                   long lifespan,
                                   TimeUnit unit)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.put(Object, Object, long, TimeUnit) . This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.put(Object, Object, long, TimeUnit) if used in LOCAL mode.

Specified by:

putAsync in interface BasicCache<K,V>

Overrides:

putAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

lifespan - lifespan of entry

unit - time unit for lifespan

Returns:

a future containing the old value replaced

putAsync

public NotifyingFuture<V> putAsync(K key,
                                   V value,
                                   long lifespan,
                                   TimeUnit lifespanUnit,
                                   long maxIdle,
                                   TimeUnit maxIdleUnit)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.put(Object, Object, long, TimeUnit, long, TimeUnit). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.put(Object, Object, long, TimeUnit, long, TimeUnit) if used in LOCAL mode.

Specified by:

putAsync in interface BasicCache<K,V>

Overrides:

putAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

lifespan - lifespan of entry

lifespanUnit - time unit for lifespan

maxIdle - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleUnit - time unit for max idle time

Returns:

a future containing the old value replaced

putAllAsync

public NotifyingFuture<Void> putAllAsync(Map<? extends K,? extends V> data)

Description copied from interface: BasicCache

Asynchronous version of Map.putAll(Map). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over Map.putAll(Map) if used in LOCAL mode.

Specified by:

putAllAsync in interface BasicCache<K,V>

Overrides:

putAllAsync in class AbstractDelegatingCache<K,V>

Parameters:

data - to store

Returns:

a future containing a void return type

putAllAsync

public NotifyingFuture<Void> putAllAsync(Map<? extends K,? extends V> data,
                                         long lifespan,
                                         TimeUnit unit)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.putAll(Map, long, TimeUnit). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.putAll(Map, long, TimeUnit) if used in LOCAL mode.

Specified by:

putAllAsync in interface BasicCache<K,V>

Overrides:

putAllAsync in class AbstractDelegatingCache<K,V>

Parameters:

data - to store

lifespan - lifespan of entry

unit - time unit for lifespan

Returns:

a future containing a void return type

putAllAsync

public NotifyingFuture<Void> putAllAsync(Map<? extends K,? extends V> data,
                                         long lifespan,
                                         TimeUnit lifespanUnit,
                                         long maxIdle,
                                         TimeUnit maxIdleUnit)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.putAll(Map, long, TimeUnit, long, TimeUnit). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.putAll(Map, long, TimeUnit, long, TimeUnit) if used in LOCAL mode.

Specified by:

putAllAsync in interface BasicCache<K,V>

Overrides:

putAllAsync in class AbstractDelegatingCache<K,V>

Parameters:

data - to store

lifespan - lifespan of entry

lifespanUnit - time unit for lifespan

maxIdle - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleUnit - time unit for max idle time

Returns:

a future containing a void return type

clearAsync

public NotifyingFuture<Void> clearAsync()

Description copied from interface: BasicCache

Asynchronous version of Map.clear(). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over Map.clear() if used in LOCAL mode.

Specified by:

clearAsync in interface BasicCache<K,V>

Overrides:

clearAsync in class AbstractDelegatingCache<K,V>

Returns:

a future containing a void return type

putIfAbsentAsync

public NotifyingFuture<V> putIfAbsentAsync(K key,
                                           V value)

Description copied from interface: BasicCache

Asynchronous version of ConcurrentMap.putIfAbsent(Object, Object). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over ConcurrentMap.putIfAbsent(Object, Object) if used in LOCAL mode.

Specified by:

putIfAbsentAsync in interface BasicCache<K,V>

Overrides:

putIfAbsentAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

Returns:

a future containing the old value replaced.

putIfAbsentAsync

public NotifyingFuture<V> putIfAbsentAsync(K key,
                                           V value,
                                           long lifespan,
                                           TimeUnit unit)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.putIfAbsent(Object, Object, long, TimeUnit) . This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.putIfAbsent(Object, Object, long, TimeUnit) if used in LOCAL mode.

Specified by:

putIfAbsentAsync in interface BasicCache<K,V>

Overrides:

putIfAbsentAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

lifespan - lifespan of entry

unit - time unit for lifespan

Returns:

a future containing the old value replaced

putIfAbsentAsync

public NotifyingFuture<V> putIfAbsentAsync(K key,
                                           V value,
                                           long lifespan,
                                           TimeUnit lifespanUnit,
                                           long maxIdle,
                                           TimeUnit maxIdleUnit)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.putIfAbsent(Object, Object, long, TimeUnit, long, TimeUnit). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.putIfAbsent(Object, Object, long, TimeUnit, long, TimeUnit) if used in LOCAL mode.

Specified by:

putIfAbsentAsync in interface BasicCache<K,V>

Overrides:

putIfAbsentAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to use

value - value to store

lifespan - lifespan of entry

lifespanUnit - time unit for lifespan

maxIdle - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleUnit - time unit for max idle time

Returns:

a future containing the old value replaced

removeAsync

public NotifyingFuture<V> removeAsync(Object key)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.remove(Object). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.remove(Object) if used in LOCAL mode.

Specified by:

removeAsync in interface BasicCache<K,V>

Overrides:

removeAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to remove

Returns:

a future containing the value removed

removeAsync

public NotifyingFuture<Boolean> removeAsync(Object key,
                                            Object value)

Description copied from interface: BasicCache

Asynchronous version of ConcurrentMap.remove(Object, Object). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over ConcurrentMap.remove(Object, Object) if used in LOCAL mode.

Specified by:

removeAsync in interface BasicCache<K,V>

Overrides:

removeAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to remove

value - value to match on

Returns:

a future containing a boolean, indicating whether the entry was removed or not

replaceAsync

public NotifyingFuture<V> replaceAsync(K key,
                                       V value)

Description copied from interface: BasicCache

Asynchronous version of ConcurrentMap.replace(Object, Object). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over ConcurrentMap.replace(Object, Object) if used in LOCAL mode.

Specified by:

replaceAsync in interface BasicCache<K,V>

Overrides:

replaceAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to remove

value - value to store

Returns:

a future containing the previous value overwritten

replaceAsync

public NotifyingFuture<V> replaceAsync(K key,
                                       V value,
                                       long lifespan,
                                       TimeUnit unit)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.replace(Object, Object, long, TimeUnit). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.replace(Object, Object, long, TimeUnit) if used in LOCAL mode.

Specified by:

replaceAsync in interface BasicCache<K,V>

Overrides:

replaceAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to remove

value - value to store

lifespan - lifespan of entry

unit - time unit for lifespan

Returns:

a future containing the previous value overwritten

replaceAsync

public NotifyingFuture<V> replaceAsync(K key,
                                       V value,
                                       long lifespan,
                                       TimeUnit lifespanUnit,
                                       long maxIdle,
                                       TimeUnit maxIdleUnit)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.replace(Object, Object, long, TimeUnit, long, TimeUnit). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.replace(Object, Object, long, TimeUnit, long, TimeUnit) if used in LOCAL mode.

Specified by:

replaceAsync in interface BasicCache<K,V>

Overrides:

replaceAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to remove

value - value to store

lifespan - lifespan of entry

lifespanUnit - time unit for lifespan

maxIdle - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleUnit - time unit for max idle time

Returns:

a future containing the previous value overwritten

replaceAsync

public NotifyingFuture<Boolean> replaceAsync(K key,
                                             V oldValue,
                                             V newValue)

Description copied from interface: BasicCache

Asynchronous version of ConcurrentMap.replace(Object, Object, Object). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over ConcurrentMap.replace(Object, Object, Object) if used in LOCAL mode.

Specified by:

replaceAsync in interface BasicCache<K,V>

Overrides:

replaceAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to remove

oldValue - value to overwrite

newValue - value to store

Returns:

a future containing a boolean, indicating whether the entry was replaced or not

replaceAsync

public NotifyingFuture<Boolean> replaceAsync(K key,
                                             V oldValue,
                                             V newValue,
                                             long lifespan,
                                             TimeUnit unit)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.replace(Object, Object, Object, long, TimeUnit). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.replace(Object, Object, Object, long, TimeUnit) if used in LOCAL mode.

Specified by:

replaceAsync in interface BasicCache<K,V>

Overrides:

replaceAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to remove

oldValue - value to overwrite

newValue - value to store

lifespan - lifespan of entry

unit - time unit for lifespan

Returns:

a future containing a boolean, indicating whether the entry was replaced or not

replaceAsync

public NotifyingFuture<Boolean> replaceAsync(K key,
                                             V oldValue,
                                             V newValue,
                                             long lifespan,
                                             TimeUnit lifespanUnit,
                                             long maxIdle,
                                             TimeUnit maxIdleUnit)

Description copied from interface: BasicCache

Asynchronous version of BasicCache.replace(Object, Object, Object, long, TimeUnit, long, TimeUnit). This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over BasicCache.replace(Object, Object, Object, long, TimeUnit, long, TimeUnit) if used in LOCAL mode.

Specified by:

replaceAsync in interface BasicCache<K,V>

Overrides:

replaceAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to remove

oldValue - value to overwrite

newValue - value to store

lifespan - lifespan of entry

lifespanUnit - time unit for lifespan

maxIdle - the maximum amount of time this key is allowed to be idle for before it is considered as expired

maxIdleUnit - time unit for max idle time

Returns:

a future containing a boolean, indicating whether the entry was replaced or not

getAsync

public NotifyingFuture<V> getAsync(K key)

Description copied from interface: BasicCache

Asynchronous version of Map.get(Object) that allows user code to retrieve the value associated with a key at a later stage, hence allowing multiple parallel get requests to be sent. Normally, when this method detects that the value is likely to be retrieved from from a remote entity, it will span a different thread in order to allow the asynchronous get call to return immediately. If the call will definitely resolve locally, for example when the cache is configured with LOCAL mode and no cache loaders are configured, the get asynchronous call will act sequentially and will have no different to Map.get(Object).

Specified by:

getAsync in interface BasicCache<K,V>

Overrides:

getAsync in class AbstractDelegatingCache<K,V>

Parameters:

key - key to retrieve

Returns:

a future that can be used to retrieve value associated with the key when this is available. The actual value returned by the future follows the same rules as Map.get(Object)

size

public int size()

Specified by:

size in interface Map<K,V>

Overrides:

size in class AbstractDelegatingCache<K,V>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

Overrides:

isEmpty in class AbstractDelegatingCache<K,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

Overrides:

containsKey in class AbstractDelegatingCache<K,V>

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

Overrides:

get in class AbstractDelegatingCache<K,V>

put

public V put(K key,
             V value)

Description copied from interface: BasicCache

If the return value of this operation will be ignored by the application, the user is strongly encouraged to use the Flag.IGNORE_RETURN_VALUES flag when invoking this method in order to make it behave as efficiently as possible (i.e. avoiding needless remote or network calls).

Specified by:

put in interface Map<K,V>

Specified by:

put in interface BasicCache<K,V>

Overrides:

put in class AbstractDelegatingCache<K,V>

remove

public V remove(Object key)

Description copied from interface: BasicCache

If the return value of this operation will be ignored by the application, the user is strongly encouraged to use the Flag.IGNORE_RETURN_VALUES flag when invoking this method in order to make it behave as efficiently as possible (i.e. avoiding needless remote or network calls).

Specified by:

remove in interface Map<K,V>

Specified by:

remove in interface BasicCache<K,V>

Overrides:

remove in class AbstractDelegatingCache<K,V>

putAll

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

Specified by:

putAll in interface Map<K,V>

Overrides:

putAll in class AbstractDelegatingCache<K,V>

clear

public void clear()

Specified by:

clear in interface Map<K,V>

Overrides:

clear in class AbstractDelegatingCache<K,V>

keySet

public Set<K> keySet()

Description copied from interface: Cache

Returns a set view of the keys contained in this cache. This set is immutable, so it cannot be modified and changes to the cache won't be reflected in the set. When this method is called on a cache configured with distribution mode, the set returned only contains the keys locally available in the cache instance. To avoid memory issues, there will be not attempt to bring keys from other nodes.

This method should only be used for debugging purposes such as to verify that the cache contains all the keys entered. Any other use involving execution of this method on a production system is not recommended.

Specified by:

keySet in interface Map<K,V>

Specified by:

keySet in interface Cache<K,V>

Overrides:

keySet in class AbstractDelegatingCache<K,V>

Returns:

a set view of the keys contained in this cache.

values

public Collection<V> values()

Description copied from interface: Cache

Returns a collection view of the values contained in this cache. This collection is immutable, so it cannot be modified and changes to the cache won't be reflected in the set. When this method is called on a cache configured with distribution mode, the collection returned only contains the values locally available in the cache instance. To avoid memory issues, there is not attempt to bring values from other nodes.

This method should only be used for testing or debugging purposes such as to verify that the cache contains all the values entered. Any other use involving execution of this method on a production system is not recommended.

Specified by:

values in interface Map<K,V>

Specified by:

values in interface Cache<K,V>

Overrides:

values in class AbstractDelegatingCache<K,V>

Returns:

a collection view of the values contained in this map.

entrySet

public Set<Map.Entry<K,V>> entrySet()

Description copied from interface: Cache

Returns a set view of the mappings contained in this cache. This set is immutable, so it cannot be modified and changes to the cache won't be reflected in the set. Besides, each element in the returned set is an immutable Map.Entry. When this method is called on a cache configured with distribution mode, the set returned only contains the mappings locally available in the cache instance. To avoid memory issues, there will be not attempt to bring mappings from other nodes.

This method should only be used for debugging purposes such as to verify that the cache contains all the mappings entered. Any other use involving execution of this method on a production system is not recommended.

Specified by:

entrySet in interface Map<K,V>

Specified by:

entrySet in interface Cache<K,V>

Overrides:

entrySet in class AbstractDelegatingCache<K,V>

Returns:

a set view of the mappings contained in this cache.

putIfAbsent

public V putIfAbsent(K key,
                     V value)

Specified by:

putIfAbsent in interface ConcurrentMap<K,V>

Overrides:

putIfAbsent in class AbstractDelegatingCache<K,V>

remove

public boolean remove(Object key,
                      Object value)

Specified by:

remove in interface ConcurrentMap<K,V>

Overrides:

remove in class AbstractDelegatingCache<K,V>

replace

public boolean replace(K key,
                       V oldValue,
                       V newValue)

Specified by:

replace in interface ConcurrentMap<K,V>

Overrides:

replace in class AbstractDelegatingCache<K,V>

replace

public V replace(K key,
                 V value)

Specified by:

replace in interface ConcurrentMap<K,V>

Overrides:

replace in class AbstractDelegatingCache<K,V>

getFlags

public EnumSet<Flag> getFlags()

addListener

public void addListener(Object listener)

Description copied from interface: Listenable

Adds a listener to the component. Typically, listeners would need to be annotated with Listener and further to that, contain methods annotated appropriately, otherwise the listener will not be registered.

See the Listener annotation for more information.

Specified by:

addListener in interface Listenable

Overrides:

addListener in class AbstractDelegatingCache<K,V>

Parameters:

listener - must not be null.

put

public V put(K key,
             V value,
             Metadata metadata)

Description copied from interface: AdvancedCache

An overloaded form of #put(K, V), which takes in an instance of Metadata which can be used to provide metadata information for the entry being stored, such as lifespan, version of value...etc.

Specified by:

put in interface AdvancedCache<K,V>

Overrides:

put in class AbstractDelegatingAdvancedCache<K,V>

Parameters:

key - key to use

value - value to store

metadata - information to store alongside the value

Returns:

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

putAsync

public NotifyingFuture<V> putAsync(K key,
                                   V value,
                                   Metadata metadata)

Description copied from interface: AdvancedCache

Asynchronous version of AdvancedCache.put(Object, Object, Metadata) which stores metadata alongside the value. This method does not block on remote calls, even if your cache mode is synchronous. Has no benefit over AdvancedCache.put(Object, Object, Metadata) if used in LOCAL mode.

Specified by:

putAsync in interface AdvancedCache<K,V>

Overrides:

putAsync in class AbstractDelegatingAdvancedCache<K,V>

Parameters:

key - key to use

value - value to store

metadata - information to store alongside the new value

Returns:

a future containing the old value replaced.

putIfAbsent

public V putIfAbsent(K key,
                     V value,
                     Metadata metadata)

Description copied from interface: AdvancedCache

An overloaded form of #putIfAbsent(K, V), which takes in an instance of Metadata which can be used to provide metadata information for the entry being stored, such as lifespan, version of value...etc. The Metadata is only stored if the call is successful.

Specified by:

putIfAbsent in interface AdvancedCache<K,V>

Overrides:

putIfAbsent in class AbstractDelegatingAdvancedCache<K,V>

Parameters:

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

value - value to be associated with the specified key

metadata - information to store alongside the new value

Returns:

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

replace

public boolean replace(K key,
                       V oldValue,
                       V value,
                       Metadata metadata)

Description copied from interface: AdvancedCache

An overloaded form of #replace(K, V, V), which takes in an instance of Metadata which can be used to provide metadata information for the entry being stored, such as lifespan, version of value...etc. The Metadata is only stored if the call is successful.

Specified by:

replace in interface AdvancedCache<K,V>

Overrides:

replace in class AbstractDelegatingAdvancedCache<K,V>

Parameters:

key - key with which the specified value is associated

oldValue - value expected to be associated with the specified key

value - value to be associated with the specified key

metadata - information to store alongside the new value

Returns:

true if the value was replaced

replace

public V replace(K key,
                 V value,
                 Metadata metadata)

Description copied from interface: AdvancedCache

An overloaded form of #replace(K, V), which takes in an instance of Metadata which can be used to provide metadata information for the entry being stored, such as lifespan, version of value...etc. The Metadata is only stored if the call is successful.

Specified by:

replace in interface AdvancedCache<K,V>

Overrides:

replace in class AbstractDelegatingAdvancedCache<K,V>

Parameters:

key - key with which the specified value is associated

value - value to be associated with the specified key

metadata - information to store alongside the new value

Returns:

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

getCacheEntry

public CacheEntry getCacheEntry(K key)

Description copied from interface: AdvancedCache

Retrieves a CacheEntry corresponding to a specific key.

Specified by:

getCacheEntry in interface AdvancedCache<K,V>

Overrides:

getCacheEntry in class AbstractDelegatingAdvancedCache<K,V>

Parameters:

key - the key whose associated cache entry is to be returned

Returns:

the cache entry to which the specified key is mapped, or null if this map contains no mapping for the key