public interface Cache<K,V> extends BasicCache<K,V>, BatchingCache, FilteringListenable<K,V>
OutOfMemoryErrorsCacheLoader, either when they are evicted as an overflow,
or all the time, to maintain persistent copies that would withstand server failure or restarts.ConcurrentMap and implements all methods accordingly. Methods like
keySet(), values() and entrySet() produce backing collections in that updates done to them
also update the original Cache instance. Certain methods on these maps can be expensive however (prohibitively so
when using a distributed cache). The size() and Map.containsValue(Object) methods upon invocation can
also be expensive just as well. The reason these methods are expensive are that they take into account entries
stored in a configured CacheLoader and remote entries when using a distributed cache.
Frequent use of these methods is not recommended if used in this manner. These aforementioned methods do take into
account in-flight transactions, however key/value pairs read in using an iterator will not be placed into the transactional
context to prevent OutOfMemoryErrors. Please note all of these methods behavior can be controlled using
a Flag to disable certain things such as taking into account the loader. Please see
each method on this interface for more details.
Also, like many ConcurrentMap implementations, Cache does not support the use of null keys or
values.
AsyncCache.putAsync(Object, Object) offer the best of both worlds
between a fully synchronous and a fully asynchronous cache in that a CompletableFuture is returned. The
CompletableFuture 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:
CompletableFuture f1 = cache.putAsync("key1", "value1");
CompletableFuture f2 = cache.putAsync("key2", "value2");
CompletableFuture 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
CompletableFuture is still returned though for API consistency.
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.
CacheContainer,
DefaultCacheManager,
Infinispan documentation,
5 Minute Usage Tutorial| Modifier and Type | Method and Description |
|---|---|
void |
clear()
Removes all mappings from the cache.
|
V |
compute(K key,
java.util.function.BiFunction<? super K,? super V,? extends V> remappingFunction) |
default V |
compute(K key,
SerializableBiFunction<? super K,? super V,? extends V> remappingFunction)
Overloaded
compute(Object, BiFunction) with Infinispan SerializableBiFunction. |
V |
computeIfAbsent(K key,
java.util.function.Function<? super K,? extends V> mappingFunction) |
default V |
computeIfAbsent(K key,
SerializableFunction<? super K,? extends V> mappingFunction)
Overloaded
computeIfAbsent(Object, Function) with Infinispan SerializableFunction. |
V |
computeIfPresent(K key,
java.util.function.BiFunction<? super K,? super V,? extends V> remappingFunction) |
default V |
computeIfPresent(K key,
SerializableBiFunction<? super K,? super V,? extends V> remappingFunction)
Overloaded
computeIfPresent(Object, BiFunction) with Infinispan SerializableBiFunction
The compiler will pick this overload for lambda parameters, making them Serializable |
CacheSet<java.util.Map.Entry<K,V>> |
entrySet()
Returns a set view of the mappings contained in this cache and cache loader across the entire cluster.
|
void |
evict(K key)
Evicts an entry from the memory of the cache.
|
AdvancedCache<K,V> |
getAdvancedCache() |
Configuration |
getCacheConfiguration() |
EmbeddedCacheManager |
getCacheManager()
Retrieves the cache manager responsible for creating this cache instance.
|
ComponentStatus |
getStatus() |
CacheSet<K> |
keySet()
Returns a set view of the keys contained in this cache and cache loader across the entire cluster.
|
V |
merge(K key,
V value,
java.util.function.BiFunction<? super V,? super V,? extends V> remappingFunction) |
default V |
merge(K key,
V value,
SerializableBiFunction<? super V,? super V,? extends V> remappingFunction)
Overloaded
merge(Object, Object, BiFunction) with Infinispan SerializableBiFunction. |
void |
putForExternalRead(K key,
V value)
Under special operating behavior, associates the value with the specified key.
|
void |
putForExternalRead(K key,
V value,
long lifespan,
java.util.concurrent.TimeUnit unit)
An overloaded form of
#putForExternalRead(K, V), which takes in lifespan parameters. |
void |
putForExternalRead(K key,
V value,
long lifespan,
java.util.concurrent.TimeUnit lifespanUnit,
long maxIdle,
java.util.concurrent.TimeUnit maxIdleUnit)
An overloaded form of
#putForExternalRead(K, V), which takes in lifespan parameters. |
default void |
shutdown()
Performs a controlled, clustered shutdown of the cache.
|
int |
size()
Returns a count of all elements in this cache and cache loader across the entire cluster.
|
void |
stop()
Stops a cache.
|
CacheCollection<V> |
values()
Returns a collection view of the values contained in this cache across the entire cluster.
|
compute, compute, computeIfAbsent, computeIfAbsent, computeIfPresent, computeIfPresent, getName, getVersion, merge, merge, put, put, put, putAll, putAll, putIfAbsent, putIfAbsent, remove, replace, replace, replace, replaceclearAsync, computeAsync, computeAsync, computeAsync, computeIfAbsentAsync, computeIfAbsentAsync, computeIfAbsentAsync, computeIfPresentAsync, computeIfPresentAsync, computeIfPresentAsync, containsKeyAsync, getAllAsync, getAsync, mergeAsync, mergeAsync, mergeAsync, putAllAsync, putAllAsync, putAllAsync, putAsync, putAsync, putAsync, putIfAbsentAsync, putIfAbsentAsync, putIfAbsentAsync, removeAsync, removeAsync, replaceAsync, replaceAsync, replaceAsync, replaceAsync, replaceAsync, replaceAsyncforEach, getOrDefault, putIfAbsent, remove, replace, replace, replaceAllcontainsKey, containsValue, equals, get, hashCode, isEmpty, putAllendBatch, startBatchaddFilteredListener, addListener, addListener, addStorageFormatFilteredListeneraddListener, getListeners, removeListenervoid putForExternalRead(K key, V value)
ConcurrentMap.putIfAbsent(Object, Object))
key - key with which the specified value is to be associated.value - value to be associated with the specified key.java.lang.IllegalStateException - if getStatus() would not return ComponentStatus.RUNNING.void putForExternalRead(K key, V value, long lifespan, java.util.concurrent.TimeUnit unit)
#putForExternalRead(K, V), which takes in lifespan parameters.key - key to usevalue - value to storelifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.unit - unit of measurement for the lifespanvoid putForExternalRead(K key, V value, long lifespan, java.util.concurrent.TimeUnit lifespanUnit, long maxIdle, java.util.concurrent.TimeUnit maxIdleUnit)
#putForExternalRead(K, V), which takes in lifespan parameters.key - key to usevalue - value to storelifespan - lifespan of the entry. Negative values are interpreted as unlimited lifespan.lifespanUnit - time unit for lifespanmaxIdle - the maximum amount of time this key is allowed to be idle for before it is considered as
expiredmaxIdleUnit - time unit for max idle timevoid evict(K key)
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.key - key to evictConfiguration getCacheConfiguration()
EmbeddedCacheManager getCacheManager()
AdvancedCache<K,V> getAdvancedCache()
ComponentStatus getStatus()
int size()
Flag.SKIP_CACHE_LOAD flag should be used to
avoid hitting the cache loader in case if this is not needed in the size calculation.
Also if you want the local contents only you can use the Flag.CACHE_MODE_LOCAL flag so
that other remote nodes are not queried for data. However the loader will still be used unless the previously
mentioned Flag.SKIP_CACHE_LOAD is also configured.
If this method is used in a transactional context, note this method will not bring additional values into the
transaction context and thus objects that haven't yet been read will act in a
IsolationLevel.READ_COMMITTED behavior irrespective of the configured
isolation level. However values that have been previously modified or read that are in the context will be
adhered to. e.g. any write modification or any previous read when using
IsolationLevel.REPEATABLE_READ
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.
CacheSet<K> keySet()
Set.toArray(), Set.toArray(Object[]),
Set.size(), Set.retainAll(Collection) and Set.iterator()
methods as they will traverse the entire contents of the cluster including a configured
CacheLoader and remote entries. The former 2 methods especially have a
very high likely hood of causing a OutOfMemoryError due to storing all the keys in the entire
cluster in the array.
Use involving execution of this method on a production system is not recommended as they can be quite expensive
operations
Flag.SKIP_CACHE_LOAD flag should be used to
avoid hitting the cache store as this will cause all entries there to be read in (albeit in a batched form to
prevent OutOfMemoryError)
Also if you want the local contents only you can use the Flag.CACHE_MODE_LOCAL flag so
that other remote nodes are not queried for data. However the loader will still be used unless the previously
mentioned Flag.SKIP_CACHE_LOAD is also configured.
CloseableIteratorSet interface which creates a
CloseableIterator instead of a regular one. This means this iterator must be
explicitly closed either through try with resource or calling the close method directly. Technically this iterator
will also close itself if you iterate fully over it, but it is safest to always make sure you close it explicitly.
UnsupportedOperationException if invoked.
Set.add(Object)
Set.addAll(java.util.Collection)CacheCollection<V> values()
Collection.toArray(), Collection.toArray(Object[]),
Collection.size(), Collection.retainAll(Collection) and Collection.iterator()
methods as they will traverse the entire contents of the cluster including a configured
CacheLoader and remote entries. The former 2 methods especially have a
very high likely hood of causing a OutOfMemoryError due to storing all the keys in the entire
cluster in the array.
Use involving execution of this method on a production system is not recommended as they can be quite expensive
operations
* Flag.SKIP_CACHE_LOAD flag should be used to
avoid hitting the cache store as this will cause all entries there to be read in (albeit in a batched form to
prevent OutOfMemoryError)
Also if you want the local contents only you can use the Flag.CACHE_MODE_LOCAL flag so
that other remote nodes are not queried for data. However the loader will still be used unless the previously
mentioned Flag.SKIP_CACHE_LOAD is also configured.
This class implements the CloseableIteratorCollection interface which creates a
CloseableIterator instead of a regular one. This means this iterator must be
explicitly closed either through try with resource or calling the close method directly. Technically this iterator
will also close itself if you iterate fully over it, but it is safest to always make sure you close it explicitly.
The iterator retrieved using CloseableIteratorCollection.iterator() supports the remove method, however the
iterator retrieved from CacheStream.iterator() will not support remove.
UnsupportedOperationException if invoked.
Set.add(Object)
Set.addAll(java.util.Collection)CacheSet<java.util.Map.Entry<K,V>> entrySet()
Set.toArray(), Set.toArray(Object[]),
Set.size(), Set.retainAll(Collection) and Set.iterator()
methods as they will traverse the entire contents of the cluster including a configured
CacheLoader and remote entries. The former 2 methods especially have a
very high likely hood of causing a OutOfMemoryError due to storing all the keys in the entire
cluster in the array.
Use involving execution of this method on a production system is not recommended as they can be quite expensive
operations
* Flag.SKIP_CACHE_LOAD flag should be used to
avoid hitting the cache store as this will cause all entries there to be read in (albeit in a batched form to
prevent OutOfMemoryError)
Also if you want the local contents only you can use the Flag.CACHE_MODE_LOCAL flag so
that other remote nodes are not queried for data. However the loader will still be used unless the previously
mentioned Flag.SKIP_CACHE_LOAD is also configured.
Map.Entry.setValue(Object) and it will update
the cache as well. Also this backing set does allow addition of a new Map.Entry(s) via the
Set.add(Object) or Set.addAll(java.util.Collection) methods.
CloseableIteratorSet interface which creates a
CloseableIterator instead of a regular one. This means this iterator must be
explicitly closed either through try with resource or calling the close method directly. Technically this iterator
will also close itself if you iterate fully over it, but it is safest to always make sure you close it explicitly.void clear()
void stop()
shutdown() method.default void shutdown()
GlobalStateConfigurationBuilder.persistentLocation(String)stop() only in clustered modes,
and only when GlobalStateConfiguration.enabled() is true, otherwise it
just behaves like stop().V computeIfAbsent(K key, java.util.function.Function<? super K,? extends V> mappingFunction)
When this method is used on a clustered cache, either replicated or distributed, the function will be serialized
to owning nodes to perform the operation in the most performant way. However this means the function must
have an appropriate Externalizer or be Serializable itself.
For transactional caches, whenever the values of the caches are collections, and the mapping function modifies the collection, the collection must be copied and not directly modified, otherwise whenever rollback is called it won't work. This limitation could disappear in following releases if technically possible.
default V computeIfAbsent(K key, SerializableFunction<? super K,? extends V> mappingFunction)
computeIfAbsent(Object, Function) with Infinispan SerializableFunction.
The compiler will pick this overload for lambda parameters, making them Serializablekey, - the key to be computedmappingFunction, - mapping function to be appliyed to the keyV computeIfPresent(K key, java.util.function.BiFunction<? super K,? super V,? extends V> remappingFunction)
When this method is used on a clustered cache, either replicated or distributed, the bifunction will be serialized
to owning nodes to perform the operation in the most performant way. However this means the bifunction must
have an appropriate Externalizer or be Serializable itself.
For transactional caches, whenever the values of the caches are collections, and the mapping function modifies the collection, the collection must be copied and not directly modified, otherwise whenever rollback is called it won't work. This limitation could disappear in following releases if technically possible.
default V computeIfPresent(K key, SerializableBiFunction<? super K,? super V,? extends V> remappingFunction)
computeIfPresent(Object, BiFunction) with Infinispan SerializableBiFunction
The compiler will pick this overload for lambda parameters, making them Serializablekey, - the key to be computedremappingFunction, - mapping function to be appliyed to the keyV compute(K key, java.util.function.BiFunction<? super K,? super V,? extends V> remappingFunction)
When this method is used on a clustered cache, either replicated or distributed, the bifunction will be serialized
to owning nodes to perform the operation in the most performant way. However this means the bifunction must
have an appropriate Externalizer or be Serializable itself.
For transactional caches, whenever the values of the caches are collections, and the mapping function modifies the collection, the collection must be copied and not directly modified, otherwise whenever rollback is called it won't work. This limitation could disappear in following releases if technically possible.
default V compute(K key, SerializableBiFunction<? super K,? super V,? extends V> remappingFunction)
compute(Object, BiFunction) with Infinispan SerializableBiFunction.
The compiler will pick this overload for lambda parameters, making them Serializablekey, - the key to be computedremappingFunction, - mapping function to be appliyed to the keyV merge(K key, V value, java.util.function.BiFunction<? super V,? super V,? extends V> remappingFunction)
When this method is used on a clustered cache, either replicated or distributed, the bifunction will be serialized
to owning nodes to perform the operation in the most performant way. However this means the bifunction must
have an appropriate Externalizer or be Serializable itself.
For transactional caches, whenever the values of the caches are collections, and the mapping function modifies the collection, the collection must be copied and not directly modified, otherwise whenever rollback is called it won't work. This limitation could disappear in following releases if technically possible.
default V merge(K key, V value, SerializableBiFunction<? super V,? super V,? extends V> remappingFunction)
merge(Object, Object, BiFunction) with Infinispan SerializableBiFunction.
The compiler will pick this overload for lambda parameters, making them Serializable.
key - key with which the resulting value is to be associatedvalue - the non-null value to be merged with the existing value associated with the key or, if no
existing value or a null value is associated with the key, to be associated with the keyremappingFunction - the function to recompute a value if present