org.infinispan

Interface AdvancedCache<K,V>

All Superinterfaces:

AsyncCache<K,V>, BasicCache<K,V>, BatchingCache, Cache<K,V>, ConcurrentMap<K,V>, FilteringListenable<K,V>, Lifecycle, Listenable, Map<K,V>

All Known Subinterfaces:

SecureCache<K,V>

All Known Implementing Classes:

AbstractDelegatingAdvancedCache, AbstractDelegatingAdvancedCache

public interface AdvancedCache<K,V>
extends Cache<K,V>

An advanced interface that exposes additional methods not available on Cache.

Since:

4.0

Author:

Manik Surtani, Galder Zamarreño, Tristan Tarrant

Method Summary

Methods

Modifier and Type	Method and Description
void	addInterceptor(CommandInterceptor i, int position) Adds a custom interceptor to the interceptor chain, at specified position, where the first interceptor in the chain is at position 0 and the last one at NUM_INTERCEPTORS - 1.
boolean	addInterceptorAfter(CommandInterceptor i, Class<? extends CommandInterceptor> afterInterceptor) Adds a custom interceptor to the interceptor chain, after an instance of the specified interceptor type.
boolean	addInterceptorBefore(CommandInterceptor i, Class<? extends CommandInterceptor> beforeInterceptor) Adds a custom interceptor to the interceptor chain, before an instance of the specified interceptor type.
void	applyDelta(K deltaAwareValueKey, Delta delta, Object... locksToAcquire) Applies the given Delta to the DeltaAware object stored under deltaAwareValueKey if and only if all locksToAcquire locks are successfully obtained
EntryIterable<K,V>	filterEntries(KeyValueFilter<? super K,? super V> filter) Retrieve the entry iterable that can be used to iterate over the contents of this cache.
AuthorizationManager	getAuthorizationManager() Retrieves the AuthorizationManager if the cache has security enabled.
AvailabilityMode	getAvailability() Returns the cache's availability.
BatchContainer	getBatchContainer() Returns the component in charge of batching cache operations.
CacheEntry<K,V>	getCacheEntry(K key) Retrieves a CacheEntry corresponding to a specific key.
ClassLoader	getClassLoader() Returns the cache loader associated associated with this cache.
ComponentRegistry	getComponentRegistry()
DataContainer<K,V>	getDataContainer() Returns the container where data is stored in the cache.
DistributionManager	getDistributionManager() Retrieves a reference to the DistributionManager if the cache is configured to use Distribution.
EvictionManager	getEvictionManager()
Map<K,V>	getGroup(String groupName) It fetches all the keys which belong to the group.
List<CommandInterceptor>	getInterceptorChain() Retrieves the current Interceptor chain.
InvocationContextContainer	getInvocationContextContainer() Deprecated. This method may be removed in a future version of Infinispan.
LockManager	getLockManager() Returns the component that deals with all aspects of acquiring and releasing locks for cache entries.
RpcManager	getRpcManager() Returns the component in charge of communication with other caches in the cluster.
Stats	getStats() Returns a Stats object that allows several statistics associated with this cache at runtime.
TransactionManager	getTransactionManager() Returns the transaction manager configured for this cache.
XAResource	getXAResource() Returns the XAResource associated with this cache which can be used to do transactional recovery.
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, 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.
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, Metadata metadata) An overloaded form of #putForExternalRead(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.
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.
void	removeGroup(String groupName) It removes all the key which belongs to a group.
void	removeInterceptor(Class<? extends CommandInterceptor> interceptorType) Removes the interceptor of specified type.
void	removeInterceptor(int position) Removes the interceptor at a specified position, where the first interceptor in the chain is at position 0 and the last one at getInterceptorChain().size() - 1.
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, 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.
void	setAvailability(AvailabilityMode availabilityMode) Manually change the availability of the 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 interface org.infinispan.Cache

entrySet, evict, getAdvancedCache, getCacheConfiguration, getCacheManager, getStatus, keySet, putForExternalRead, putForExternalRead, putForExternalRead, size, values

Methods inherited from interface org.infinispan.commons.api.BasicCache

getName, getVersion, put, put, put, putAll, putAll, putIfAbsent, putIfAbsent, remove, replace, replace, replace, replace

Methods inherited from interface org.infinispan.commons.api.AsyncCache

clearAsync, getAsync, putAllAsync, putAllAsync, putAllAsync, putAsync, putAsync, putAsync, putIfAbsentAsync, putIfAbsentAsync, putIfAbsentAsync, removeAsync, removeAsync, replaceAsync, replaceAsync, replaceAsync, replaceAsync, replaceAsync, replaceAsync

Methods inherited from interface org.infinispan.commons.api.Lifecycle

start, stop

Methods inherited from interface org.infinispan.commons.api.BatchingCache

endBatch, startBatch

Methods inherited from interface org.infinispan.notifications.FilteringListenable

addListener, addListener

Methods inherited from interface org.infinispan.notifications.Listenable

addListener, getListeners, removeListener

Method Detail

withFlags

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

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

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.

addInterceptor

void addInterceptor(CommandInterceptor i,
                  int position)

Adds a custom interceptor to the interceptor chain, at specified position, where the first interceptor in the chain is at position 0 and the last one at NUM_INTERCEPTORS - 1.

Parameters:

i - the interceptor to add

position - the position to add the interceptor

addInterceptorAfter

boolean addInterceptorAfter(CommandInterceptor i,
                          Class<? extends CommandInterceptor> afterInterceptor)

Adds a custom interceptor to the interceptor chain, after an instance of the specified interceptor type. Throws a cache exception if it cannot find an interceptor of the specified type.

Parameters:

i - interceptor to add

afterInterceptor - interceptor type after which to place custom interceptor

Returns:

true if successful, false otherwise.

addInterceptorBefore

boolean addInterceptorBefore(CommandInterceptor i,
                           Class<? extends CommandInterceptor> beforeInterceptor)

Adds a custom interceptor to the interceptor chain, before an instance of the specified interceptor type. Throws a cache exception if it cannot find an interceptor of the specified type.

Parameters:

i - interceptor to add

beforeInterceptor - interceptor type before which to place custom interceptor

Returns:

true if successful, false otherwise.

removeInterceptor

void removeInterceptor(int position)

Removes the interceptor at a specified position, where the first interceptor in the chain is at position 0 and the last one at getInterceptorChain().size() - 1.

Parameters:

position - the position at which to remove an interceptor

removeInterceptor

void removeInterceptor(Class<? extends CommandInterceptor> interceptorType)

Removes the interceptor of specified type.

Parameters:

interceptorType - type of interceptor to remove

getInterceptorChain

List<CommandInterceptor> getInterceptorChain()

Retrieves the current Interceptor chain.

Returns:

an immutable List of CommandInterceptors configured for this cache

getEvictionManager

EvictionManager getEvictionManager()

Returns:

the eviction manager - if one is configured - for this cache instance

getComponentRegistry

ComponentRegistry getComponentRegistry()

Returns:

the component registry for this cache instance

getDistributionManager

DistributionManager getDistributionManager()

Retrieves a reference to the DistributionManager if the cache is configured to use Distribution. Otherwise, returns a null.

Returns:

a DistributionManager, or null.

getAuthorizationManager

AuthorizationManager getAuthorizationManager()

Retrieves the AuthorizationManager if the cache has security enabled. Otherwise returns null

Returns:

an AuthorizationManager or null

lock

boolean lock(K... keys)

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.

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.

Throws:

TimeoutException - if the lock cannot be acquired within the configured lock acquisition time.

lock

boolean lock(Collection<? extends K> keys)

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.

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.

Throws:

TimeoutException - if the lock cannot be acquired within the configured lock acquisition time.

applyDelta

void applyDelta(K deltaAwareValueKey,
              Delta delta,
              Object... locksToAcquire)

Applies the given Delta to the DeltaAware object stored under deltaAwareValueKey if and only if all locksToAcquire locks are successfully obtained

Parameters:

deltaAwareValueKey - the key for DeltaAware object

delta - the delta to be applied to DeltaAware object

locksToAcquire - keys to be locked in DeltaAware scope

getRpcManager

RpcManager getRpcManager()

Returns the component in charge of communication with other caches in the cluster. If the cache's ClusteringConfiguration.cacheMode() is CacheMode.LOCAL, this method will return null.

Returns:

the RPC manager component associated with this cache instance or null

getBatchContainer

BatchContainer getBatchContainer()

Returns the component in charge of batching cache operations.

Returns:

the batching component associated with this cache instance

getInvocationContextContainer

@Deprecated
InvocationContextContainer getInvocationContextContainer()

Deprecated. This method may be removed in a future version of Infinispan.

Returns the component in charge of managing the interactions between the cache operations and the context information associated with them.

Returns:

the invocation context container component

getDataContainer

DataContainer<K,V> getDataContainer()

Returns the container where data is stored in the cache. Users should interact with this component with care because direct calls on it bypass the internal interceptors and other infrastructure in place to guarantee the consistency of data.

Returns:

the data container associated with this cache instance

getTransactionManager

TransactionManager getTransactionManager()

Returns the transaction manager configured for this cache. If no transaction manager was configured, this method returns null.

Returns:

the transaction manager associated with this cache instance or null

getLockManager

LockManager getLockManager()

Returns the component that deals with all aspects of acquiring and releasing locks for cache entries.

Returns:

retrieves the lock manager associated with this cache instance

getStats

Stats getStats()

Returns a Stats object that allows several statistics associated with this cache at runtime.

Returns:

this cache's Stats object

getXAResource

XAResource getXAResource()

Returns the XAResource associated with this cache which can be used to do transactional recovery.

Returns:

an instance of XAResource

getClassLoader

ClassLoader getClassLoader()

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.

Returns:

this cache's cache loader

with

AdvancedCache<K,V> with(ClassLoader classLoader)

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 StoreAsBinaryConfiguration, 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);
 

Returns:

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

put

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.

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.

Since:

5.3

replace

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. The Metadata is only stored if the call is successful.

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.

Since:

5.3

replace

boolean replace(K key,
              V oldValue,
              V newValue,
              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. The Metadata is only stored if the call is successful.

Parameters:

key - key with which the specified value is associated

oldValue - value expected to be associated with the specified key

newValue - value to be associated with the specified key

metadata - information to store alongside the new value

Returns:

true if the value was replaced

Since:

5.3

putIfAbsent

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. The Metadata is only stored if the call is successful.

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.

Since:

5.3

putForExternalRead

void putForExternalRead(K key,
                      V value,
                      Metadata metadata)

An overloaded form of #putForExternalRead(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.

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

Since:

7.0

putAsync

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

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.

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.

Since:

5.3

getCacheEntry

CacheEntry<K,V> getCacheEntry(K key)

Retrieves a CacheEntry corresponding to a specific key.

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

Since:

5.3

filterEntries

EntryIterable<K,V> filterEntries(KeyValueFilter<? super K,? super V> filter)

Retrieve the entry iterable that can be used to iterate over the contents of this cache. Note that every invocation of Iterable.iterator() will cause a new request chain to retrieve all of the values in the cache, including any configured loaders. This iterator is performed in memory sensitive way and thus works for distributed caches unlike Cache.entrySet().

Whenever possible a user should provide a converter through EntryIterable.converter(org.infinispan.filter.Converter) to reduce value payloads or create projection views.

This iterator does not participate in any ongoing transaction that may be present. This is because IsolationLevel.REPEATABLE_READ transactions have to keep track of all the entries they have read (which in this case would include the entries that did not match the filter). Keeping all the values on a single node would negate the benefits of using a filter and/or converter, and in many cases it would cause OutOfMemoryErrors. If it is desired to remove entries the BasicCache.remove(Object) method or another similar method may be used which would participate in the transaction

The iterable should always be closed after finished with it, using the standard try/finally or try with resource idioms to ensure that any current resources are freed if an exception prevents full iteration of iterator. Note this will prevent any ongoing iterators that were created from it from progressing further.

Parameters:

filter - The filter to use. Note this is required and for distributed caches must be serializable. Callbacks to the filter will never provide a key or value that will be null.

getGroup

Map<K,V> getGroup(String groupName)

It fetches all the keys which belong to the group.

Semantically, it iterates over all the keys in memory and persistence, and performs a read operation in the keys found. Multiple invocations inside a transaction ensures that all the keys previous read are returned and it may return newly added keys to the group from other committed transactions (also known as phantom reads).

The map returned is immutable and represents the group at the time of the invocation. If you want to add or remove keys from a group use BasicCache.put(Object, Object) and BasicCache.remove(Object). To remove all the keys in the group use AdvancedCache.removeGroup(String).

To improve performance you may use the flag Flag.SKIP_CACHE_LOAD to avoid fetching the key/value from persistence. However, you will get an inconsistent snapshot of the group.

Parameters:

groupName - the group name.

Returns:

an immutable Map with the key/value pairs.

removeGroup

void removeGroup(String groupName)

It removes all the key which belongs to a group.

Semantically, it fetches the most recent group keys/values and removes them.

Note that, concurrent addition perform by other transactions/threads to the group may not be removed.

Parameters:

groupName - the group name.

getAvailability

AvailabilityMode getAvailability()

Returns the cache's availability. In local mode this method will always return AvailabilityMode.AVAILABLE. In clustered mode, the PartitionHandlingManager is queried to obtain the availability mode.

setAvailability

void setAvailability(AvailabilityMode availabilityMode)

Manually change the availability of the cache. Doesn't change anything if the cache is not clustered or partition handling is not enabled (PartitionHandlingConfiguration.enabled().