Package org.infinispan.commons.api
Interface AsyncCache<K,V>
- All Known Subinterfaces:
AdvancedCache<K,
,V> BasicCache<K,
,V> Cache<K,
,V> InternalRemoteCache<K,
,V> RemoteCache<K,
,V> SecureCache<K,
V>
- All Known Implementing Classes:
AbstractDelegatingAdvancedCache
,AbstractDelegatingCache
,CacheImpl
,DecoratedCache
,DelegatingRemoteCache
,EncoderCache
,InvalidatedNearRemoteCache
,RemoteCacheImpl
,RemoteCacheSupport
,SecureCacheImpl
,SimpleCacheImpl
,StatsCollectingCache
public interface AsyncCache<K,V>
AsyncCache. This interface is implemented by caches which support asynchronous variants of the various
put/get/remove/clear/replace/putAll methods
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
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.
These methods can have benefit over their sync versions even in LOCAL mode.
- Since:
- 6.0
- Author:
- Mircea Markus, Manik Surtani, Galder ZamarreƱo, Tristan Tarrant
-
Method Summary
Modifier and TypeMethodDescriptionAsynchronous version ofMap.clear()
.computeAsync
(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction) Asynchronous version ofConcurrentMap.compute(Object, BiFunction)
.computeAsync
(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit) Asynchronous version ofBasicCache.compute(Object, BiFunction, long, TimeUnit)
.computeAsync
(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.compute(Object, BiFunction, long, TimeUnit, long, TimeUnit)
.computeIfAbsentAsync
(K key, Function<? super K, ? extends V> mappingFunction) Asynchronous version ofConcurrentMap.computeIfAbsent(Object, Function)
.computeIfAbsentAsync
(K key, Function<? super K, ? extends V> mappingFunction, long lifespan, TimeUnit lifespanUnit) Asynchronous version ofBasicCache.computeIfAbsent(Object, Function, long, TimeUnit)
.computeIfAbsentAsync
(K key, Function<? super K, ? extends V> mappingFunction, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.computeIfAbsent(Object, Function, long, TimeUnit, long, TimeUnit)
.computeIfPresentAsync
(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction) Asynchronous version ofConcurrentMap.computeIfPresent(Object, BiFunction)
.computeIfPresentAsync
(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit) Asynchronous version ofBasicCache.computeIfPresent(Object, BiFunction, long, TimeUnit)
.computeIfPresentAsync
(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.computeIfPresent(Object, BiFunction, long, TimeUnit, long, TimeUnit)
.default CompletableFuture
<Boolean> containsKeyAsync
(K key) Asynchronous version ofMap.containsKey(Object)
default CompletableFuture
<Map<K, V>> getAllAsync
(Set<?> keys) TODO This should be in AdvancedCache with getAllAsynchronous version ofMap.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.mergeAsync
(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction) Asynchronous version ofConcurrentMap.merge(Object, Object, BiFunction)
.mergeAsync
(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit) Asynchronous version ofBasicCache.merge(Object, Object, BiFunction, long, TimeUnit)
.mergeAsync
(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.merge(Object, Object, BiFunction, long, TimeUnit, long, TimeUnit)
.putAllAsync
(Map<? extends K, ? extends V> data) Asynchronous version ofMap.putAll(Map)
.putAllAsync
(Map<? extends K, ? extends V> data, long lifespan, TimeUnit unit) Asynchronous version ofBasicCache.putAll(Map, long, TimeUnit)
.putAllAsync
(Map<? extends K, ? extends V> data, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.putAll(Map, long, TimeUnit, long, TimeUnit)
.Asynchronous version ofBasicCache.put(Object, Object)
.Asynchronous version ofBasicCache.put(Object, Object, long, TimeUnit)
.Asynchronous version ofBasicCache.put(Object, Object, long, TimeUnit, long, TimeUnit)
.putIfAbsentAsync
(K key, V value) Asynchronous version ofConcurrentMap.putIfAbsent(Object, Object)
.putIfAbsentAsync
(K key, V value, long lifespan, TimeUnit unit) Asynchronous version ofBasicCache.putIfAbsent(Object, Object, long, TimeUnit)
.putIfAbsentAsync
(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.putIfAbsent(Object, Object, long, TimeUnit, long, TimeUnit)
.removeAsync
(Object key) Asynchronous version ofBasicCache.remove(Object)
.removeAsync
(Object key, Object value) Asynchronous version ofConcurrentMap.remove(Object, Object)
.replaceAsync
(K key, V value) Asynchronous version ofConcurrentMap.replace(Object, Object)
.replaceAsync
(K key, V value, long lifespan, TimeUnit unit) Asynchronous version ofBasicCache.replace(Object, Object, long, TimeUnit)
.replaceAsync
(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.replace(Object, Object, long, TimeUnit, long, TimeUnit)
.replaceAsync
(K key, V oldValue, V newValue) Asynchronous version ofConcurrentMap.replace(Object, Object, Object)
.replaceAsync
(K key, V oldValue, V newValue, long lifespan, TimeUnit unit) Asynchronous version ofBasicCache.replace(Object, Object, Object, long, TimeUnit)
.replaceAsync
(K key, V oldValue, V newValue, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.replace(Object, Object, Object, long, TimeUnit, long, TimeUnit)
.Asynchronous version ofMap.size()
.
-
Method Details
-
putAsync
Asynchronous version ofBasicCache.put(Object, Object)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to usevalue
- value to store- Returns:
- a future containing the old value replaced.
-
putAsync
Asynchronous version ofBasicCache.put(Object, Object, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to usevalue
- value to storelifespan
- lifespan of entryunit
- time unit for lifespan- Returns:
- a future containing the old value replaced
-
putAsync
CompletableFuture<V> putAsync(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.put(Object, Object, long, TimeUnit, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to usevalue
- value to storelifespan
- lifespan of entrylifespanUnit
- 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 time- Returns:
- a future containing the old value replaced
-
putAllAsync
Asynchronous version ofMap.putAll(Map)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
data
- to store- Returns:
- a future containing a void return type
-
putAllAsync
CompletableFuture<Void> putAllAsync(Map<? extends K, ? extends V> data, long lifespan, TimeUnit unit) Asynchronous version ofBasicCache.putAll(Map, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
data
- to storelifespan
- lifespan of entryunit
- time unit for lifespan- Returns:
- a future containing a void return type
-
putAllAsync
CompletableFuture<Void> putAllAsync(Map<? extends K, ? extends V> data, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.putAll(Map, long, TimeUnit, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
data
- to storelifespan
- lifespan of entrylifespanUnit
- 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 time- Returns:
- a future containing a void return type
-
clearAsync
CompletableFuture<Void> clearAsync()Asynchronous version ofMap.clear()
. This method does not block on remote calls, even if your cache mode is synchronous.- Returns:
- a future containing a void return type
-
sizeAsync
CompletableFuture<Long> sizeAsync()Asynchronous version ofMap.size()
. This method does not block on remote calls, even if your cache mode is synchronous.- Returns:
- a future containing the count of the cache
-
putIfAbsentAsync
Asynchronous version ofConcurrentMap.putIfAbsent(Object, Object)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to usevalue
- value to store- Returns:
- a future containing the old value replaced.
-
putIfAbsentAsync
Asynchronous version ofBasicCache.putIfAbsent(Object, Object, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to usevalue
- value to storelifespan
- lifespan of entryunit
- time unit for lifespan- Returns:
- a future containing the old value replaced
-
putIfAbsentAsync
CompletableFuture<V> putIfAbsentAsync(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.putIfAbsent(Object, Object, long, TimeUnit, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to usevalue
- value to storelifespan
- lifespan of entrylifespanUnit
- 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 time- Returns:
- a future containing the old value replaced
-
removeAsync
Asynchronous version ofBasicCache.remove(Object)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to remove- Returns:
- a future containing the value removed
-
removeAsync
Asynchronous version ofConcurrentMap.remove(Object, Object)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to removevalue
- value to match on- Returns:
- a future containing a boolean, indicating whether the entry was removed or not
-
replaceAsync
Asynchronous version ofConcurrentMap.replace(Object, Object)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to removevalue
- value to store- Returns:
- a future containing the previous value overwritten
-
replaceAsync
Asynchronous version ofBasicCache.replace(Object, Object, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to removevalue
- value to storelifespan
- lifespan of entryunit
- time unit for lifespan- Returns:
- a future containing the previous value overwritten
-
replaceAsync
CompletableFuture<V> replaceAsync(K key, V value, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.replace(Object, Object, long, TimeUnit, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to removevalue
- value to storelifespan
- lifespan of entrylifespanUnit
- 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 time- Returns:
- a future containing the previous value overwritten
-
replaceAsync
Asynchronous version ofConcurrentMap.replace(Object, Object, Object)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to removeoldValue
- value to overwritenewValue
- value to store- Returns:
- a future containing a boolean, indicating whether the entry was replaced or not
-
replaceAsync
CompletableFuture<Boolean> replaceAsync(K key, V oldValue, V newValue, long lifespan, TimeUnit unit) Asynchronous version ofBasicCache.replace(Object, Object, Object, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to removeoldValue
- value to overwritenewValue
- value to storelifespan
- lifespan of entryunit
- time unit for lifespan- Returns:
- a future containing a boolean, indicating whether the entry was replaced or not
-
replaceAsync
CompletableFuture<Boolean> replaceAsync(K key, V oldValue, V newValue, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.replace(Object, Object, Object, long, TimeUnit, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Parameters:
key
- key to removeoldValue
- value to overwritenewValue
- value to storelifespan
- lifespan of entrylifespanUnit
- 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 time- Returns:
- a future containing a boolean, indicating whether the entry was replaced or not
-
getAsync
Asynchronous version ofMap.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 stores are configured, the get asynchronous call will act sequentially and will have no different toMap.get(Object)
.- 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)
-
containsKeyAsync
Asynchronous version ofMap.containsKey(Object)
- Parameters:
key
- key to retrieve- Returns:
- future containing true if the mapping exists.
- Since:
- 9.2
-
getAllAsync
TODO This should be in AdvancedCache with getAll- Since:
- 9.2
-
computeAsync
CompletableFuture<V> computeAsync(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction) Asynchronous version ofConcurrentMap.compute(Object, BiFunction)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-
computeAsync
CompletableFuture<V> computeAsync(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit) Asynchronous version ofBasicCache.compute(Object, BiFunction, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-
computeAsync
CompletableFuture<V> computeAsync(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.compute(Object, BiFunction, long, TimeUnit, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-
computeIfAbsentAsync
Asynchronous version ofConcurrentMap.computeIfAbsent(Object, Function)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-
computeIfAbsentAsync
CompletableFuture<V> computeIfAbsentAsync(K key, Function<? super K, ? extends V> mappingFunction, long lifespan, TimeUnit lifespanUnit) Asynchronous version ofBasicCache.computeIfAbsent(Object, Function, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-
computeIfAbsentAsync
CompletableFuture<V> computeIfAbsentAsync(K key, Function<? super K, ? extends V> mappingFunction, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.computeIfAbsent(Object, Function, long, TimeUnit, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-
computeIfPresentAsync
CompletableFuture<V> computeIfPresentAsync(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction) Asynchronous version ofConcurrentMap.computeIfPresent(Object, BiFunction)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-
computeIfPresentAsync
CompletableFuture<V> computeIfPresentAsync(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit) Asynchronous version ofBasicCache.computeIfPresent(Object, BiFunction, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-
computeIfPresentAsync
CompletableFuture<V> computeIfPresentAsync(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.computeIfPresent(Object, BiFunction, long, TimeUnit, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-
mergeAsync
CompletableFuture<V> mergeAsync(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction) Asynchronous version ofConcurrentMap.merge(Object, Object, BiFunction)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-
mergeAsync
CompletableFuture<V> mergeAsync(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit) Asynchronous version ofBasicCache.merge(Object, Object, BiFunction, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-
mergeAsync
CompletableFuture<V> mergeAsync(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit) Asynchronous version ofBasicCache.merge(Object, Object, BiFunction, long, TimeUnit, long, TimeUnit)
. This method does not block on remote calls, even if your cache mode is synchronous.- Since:
- 9.4
-