org.infinispan

Interface Cache<K,V>

All Superinterfaces:

org.infinispan.api.BasicCache<K,V>, org.infinispan.notifications.FilteringListenable, org.infinispan.notifications.Listenable

All Known Subinterfaces:

AdvancedCache<K,V>

All Known Implementing Classes:

AbstractDelegatingAdvancedCache, AbstractDelegatingCache, CacheImpl, DecoratedCache

public interface Cache<K,V>
extends org.infinispan.api.BasicCache<K,V>, org.infinispan.notifications.FilteringListenable

The central interface of Infinispan. A Cache provides a highly concurrent, optionally distributed data structure with additional features such as:

• JTA transaction compatibility
• Eviction support for evicting entries from memory to prevent OutOfMemoryErrors
• Persisting entries to a CacheLoader, either when they are evicted as an overflow, or all the time, to maintain persistent copies that would withstand server failure or restarts.

For convenience, Cache extends ConcurrentMap and implements all methods accordingly, although methods like Map.keySet(), Map.values() and Map.entrySet() are expensive (prohibitively so when using a distributed cache) and frequent use of these methods is not recommended.

size() provides the size of the local, internal data container only. This does not take into account in-fly transactions, entries stored in a cache store, or remote entries. It may also take into consideration entries that have expired but haven't yet been removed from the internal container, as well as entries in the L1 cache if L1 is enabled along with distribution as a clustering mode. See the Infinispan User Guide section on L1 caching for more details.

Also, like many ConcurrentMap implementations, Cache does not support the use of null keys or values.

Unsupported operations

#containsValue(Object)

Asynchronous operations

Cache also supports the use of "async" remote operations. Note that these methods only really make sense if you are using a clustered cache. I.e., when used in LOCAL mode, these "async" operations offer no benefit whatsoever. These methods, such as BasicCache.putAsync(Object, Object) offer the best of both worlds between a fully synchronous and a fully asynchronous cache in that a NotifyingFuture is returned. The NotifyingFuture can then be ignored or thrown away for typical asynchronous behaviour, or queried for synchronous behaviour, which would block until any remote calls complete. Note that all remote calls are, as far as the transport is concerned, synchronous. This allows you the guarantees that remote calls succeed, while not blocking your application thread unnecessarily. For example, usage such as the following could benefit from the async operations:

   NotifyingFuture f1 = cache.putAsync("key1", "value1");
   NotifyingFuture f2 = cache.putAsync("key2", "value2");
   NotifyingFuture f3 = cache.putAsync("key3", "value3");
   f1.get();
   f2.get();
   f3.get();
 

The net result is behavior similar to synchronous RPC calls in that at the end, you have guarantees that all calls completed successfully, but you have the added benefit that the three calls could happen in parallel. This is especially advantageous if the cache uses distribution and the three keys map to different cache instances in the cluster.

Also, the use of async operations when within a transaction return your local value only, as expected. A NotifyingFuture is still returned though for API consistency.

Constructing a Cache

An instance of the Cache is usually obtained by using a CacheContainer.

   CacheManager cm = new DefaultCacheManager(); // optionally pass in a default configuration
   Cache c = cm.getCache();
 

See the CacheContainer interface for more details on providing specific configurations, using multiple caches in the same JVM, etc.

Please see the Infinispan documentation and/or the 5 Minute Usage Tutorial for more details.

Since:

4.0

Author:

Mircea.Markus@jboss.com, Manik Surtani, Galder Zamarreño

See Also:

CacheContainer, DefaultCacheManager, Infinispan documentation, 5 Minute Usage Tutorial

Method Summary

Methods

Modifier and Type	Method and Description
java.util.Set<java.util.Map.Entry<K,V>>	entrySet() Returns a set view of the mappings contained in this cache and cache loader.
void	evict(K key) Evicts an entry from the memory of the cache.
AdvancedCache<K,V>	getAdvancedCache()
Configuration	getCacheConfiguration()
org.infinispan.manager.EmbeddedCacheManager	getCacheManager() Retrieves the cache manager responsible for creating this cache instance.
org.infinispan.lifecycle.ComponentStatus	getStatus()
java.util.Set<K>	keySet() Returns a set view of the keys contained in this cache and cache loader.
void	putForExternalRead(K key, V value) Under special operating behavior, associates the value with the specified key.
int	size() Returns a count of all elements in this cache and cache loader.
java.util.Collection<V>	values() Returns a collection view of the values contained in this cache.

Methods inherited from interface org.infinispan.api.BasicCache

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.notifications.FilteringListenable

addListener

Methods inherited from interface org.infinispan.notifications.Listenable

addListener, getListeners, removeListener

Method Detail

putForExternalRead

void putForExternalRead(K key,
                      V value)

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.

Parameters:

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

value - value to be associated with the specified key.

Throws:

java.lang.IllegalStateException - if getStatus() would not return ComponentStatus.RUNNING.

evict

void evict(K key)

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

Parameters:

key - key to evict

getCacheConfiguration

Configuration getCacheConfiguration()

getCacheManager

org.infinispan.manager.EmbeddedCacheManager getCacheManager()

Retrieves the cache manager responsible for creating this cache instance.

Returns:

a cache manager

getAdvancedCache

AdvancedCache<K,V> getAdvancedCache()

getStatus

org.infinispan.lifecycle.ComponentStatus getStatus()

size

int size()

Returns a count of all elements in this cache and cache loader. To avoid performance issues, there will be no attempt to count keys from other nodes.

If there are memory concerns then the org.infinispan.context.Flag.SKIP_CACHE_LOAD flag should be used to avoid hitting the cache store as all local keys will be loaded into memory at once.

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.

Returns:

the number of key-value mappings in this cache and cache loader

keySet

java.util.Set<K> keySet()

Returns a set view of the keys contained in this cache and cache loader. 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 including the cache loader if provided. To avoid memory issues, there will be not attempt to bring keys from other nodes.

If there are memory concerns then the org.infinispan.context.Flag.SKIP_CACHE_LOAD flag should be used to avoid hitting the cache store as all local keys will be in memory at once.

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.

Returns:

a set view of the keys contained in this cache and cache loader.

values

java.util.Collection<V> values()

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 including the cache loader if provided. To avoid memory issues, there is no attempt to bring values from other nodes.

If there are memory concerns then the org.infinispan.context.Flag.SKIP_CACHE_LOAD flag should be used to avoid hitting the cache store as all local values will be in memory at once.

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.

Returns:

a collection view of the values contained in this cache and cache loader.

entrySet

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

Returns a set view of the mappings contained in this cache and cache loader. 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.

If there are memory concerns then the org.infinispan.context.Flag.SKIP_CACHE_LOAD flag should be used to avoid hitting the cache store as all local entries will be in memory at once.

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.

Returns:

a set view of the mappings contained in this cache and cache loader