Package org.infinispan.commons.api

Interface AsyncCache<K,V>

All Known Subinterfaces:

BasicCache<K,V>, RemoteCache<K,V>

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 Type	Method	Description
CompletableFuture<Void>	clearAsync()	Asynchronous version of Map.clear().
CompletableFuture<V>	computeAsync(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)	Asynchronous version of ConcurrentMap.compute(Object, BiFunction).
CompletableFuture<V>	computeAsync(K key, BiFunction<? super K,? super V,? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit)	Asynchronous version of BasicCache.compute(Object, BiFunction, long, TimeUnit).
CompletableFuture<V>	computeAsync(K key, BiFunction<? super K,? super V,? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit)	Asynchronous version of BasicCache.compute(Object, BiFunction, long, TimeUnit, long, TimeUnit).
CompletableFuture<V>	computeIfAbsentAsync(K key, Function<? super K,? extends V> mappingFunction)	Asynchronous version of ConcurrentMap.computeIfAbsent(Object, Function).
CompletableFuture<V>	computeIfAbsentAsync(K key, Function<? super K,? extends V> mappingFunction, long lifespan, TimeUnit lifespanUnit)	Asynchronous version of BasicCache.computeIfAbsent(Object, Function, long, TimeUnit).
CompletableFuture<V>	computeIfAbsentAsync(K key, Function<? super K,? extends V> mappingFunction, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit)	Asynchronous version of BasicCache.computeIfAbsent(Object, Function, long, TimeUnit, long, TimeUnit).
CompletableFuture<V>	computeIfPresentAsync(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)	Asynchronous version of ConcurrentMap.computeIfPresent(Object, BiFunction).
CompletableFuture<V>	computeIfPresentAsync(K key, BiFunction<? super K,? super V,? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit)	Asynchronous version of BasicCache.computeIfPresent(Object, BiFunction, long, TimeUnit) .
CompletableFuture<V>	computeIfPresentAsync(K key, BiFunction<? super K,? super V,? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit, long maxIdle, TimeUnit maxIdleUnit)	Asynchronous version of BasicCache.computeIfPresent(Object, BiFunction, long, TimeUnit, long, TimeUnit) .
default CompletableFuture<Boolean>	containsKeyAsync(K key)	Asynchronous version of Map.containsKey(Object)
default CompletableFuture<Map<K,V>>	getAllAsync(Set<?> keys)
CompletableFuture<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.
CompletableFuture<V>	mergeAsync(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)	Asynchronous version of ConcurrentMap.merge(Object, Object, BiFunction).
CompletableFuture<V>	mergeAsync(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction, long lifespan, TimeUnit lifespanUnit)	Asynchronous version of BasicCache.merge(Object, Object, BiFunction, long, TimeUnit).
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 of BasicCache.merge(Object, Object, BiFunction, long, TimeUnit, long, TimeUnit).
CompletableFuture<Void>	putAllAsync(Map<? extends K,? extends V> data)	Asynchronous version of Map.putAll(Map).
CompletableFuture<Void>	putAllAsync(Map<? extends K,? extends V> data, long lifespan, TimeUnit unit)	Asynchronous version of BasicCache.putAll(Map, long, TimeUnit).
CompletableFuture<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).
CompletableFuture<V>	putAsync(K key, V value)	Asynchronous version of BasicCache.put(Object, Object).
CompletableFuture<V>	putAsync(K key, V value, long lifespan, TimeUnit unit)	Asynchronous version of BasicCache.put(Object, Object, long, TimeUnit) .
CompletableFuture<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).
CompletableFuture<V>	putIfAbsentAsync(K key, V value)	Asynchronous version of ConcurrentMap.putIfAbsent(Object, Object).
CompletableFuture<V>	putIfAbsentAsync(K key, V value, long lifespan, TimeUnit unit)	Asynchronous version of BasicCache.putIfAbsent(Object, Object, long, TimeUnit) .
CompletableFuture<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).
CompletableFuture<V>	removeAsync(Object key)	Asynchronous version of BasicCache.remove(Object).
CompletableFuture<Boolean>	removeAsync(Object key, Object value)	Asynchronous version of ConcurrentMap.remove(Object, Object).
CompletableFuture<V>	replaceAsync(K key, V value)	Asynchronous version of ConcurrentMap.replace(Object, Object).
CompletableFuture<V>	replaceAsync(K key, V value, long lifespan, TimeUnit unit)	Asynchronous version of BasicCache.replace(Object, Object, long, TimeUnit).
CompletableFuture<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).
CompletableFuture<Boolean>	replaceAsync(K key, V oldValue, V newValue)	Asynchronous version of ConcurrentMap.replace(Object, Object, Object).
CompletableFuture<Boolean>	replaceAsync(K key, V oldValue, V newValue, long lifespan, TimeUnit unit)	Asynchronous version of BasicCache.replace(Object, Object, Object, long, TimeUnit).
CompletableFuture<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).

Method Detail

putAsync

CompletableFuture<V> putAsync(K key,
                              V value)

Asynchronous version of BasicCache.put(Object, Object). This method does not block on remote calls, even if your cache mode is synchronous.

Parameters:

key - key to use

value - value to store

Returns:

a future containing the old value replaced.

putAsync

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

Asynchronous version of BasicCache.put(Object, Object, long, TimeUnit) . This method does not block on remote calls, even if your cache mode is synchronous.

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

CompletableFuture<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). This method does not block on remote calls, even if your cache mode is synchronous.

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

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

Asynchronous version of Map.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 of BasicCache.putAll(Map, long, TimeUnit). This method does not block on remote calls, even if your cache mode is synchronous.

Parameters:

data - to store

lifespan - lifespan of entry

unit - 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 of BasicCache.putAll(Map, long, TimeUnit, long, TimeUnit). This method does not block on remote calls, even if your cache mode is synchronous.

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

CompletableFuture<Void> clearAsync()

Asynchronous version of Map.clear(). This method does not block on remote calls, even if your cache mode is synchronous.

Returns:

a future containing a void return type

putIfAbsentAsync

CompletableFuture<V> putIfAbsentAsync(K key,
                                      V value)

Asynchronous version of ConcurrentMap.putIfAbsent(Object, Object). This method does not block on remote calls, even if your cache mode is synchronous.

Parameters:

key - key to use

value - value to store

Returns:

a future containing the old value replaced.

putIfAbsentAsync

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

Asynchronous version of BasicCache.putIfAbsent(Object, Object, long, TimeUnit) . This method does not block on remote calls, even if your cache mode is synchronous.

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

CompletableFuture<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). This method does not block on remote calls, even if your cache mode is synchronous.

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

CompletableFuture<V> removeAsync(Object key)

Asynchronous version of BasicCache.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

CompletableFuture<Boolean> removeAsync(Object key,
                                       Object value)

Asynchronous version of ConcurrentMap.remove(Object, Object). This method does not block on remote calls, even if your cache mode is synchronous.

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

CompletableFuture<V> replaceAsync(K key,
                                  V value)

Asynchronous version of ConcurrentMap.replace(Object, Object). This method does not block on remote calls, even if your cache mode is synchronous.

Parameters:

key - key to remove

value - value to store

Returns:

a future containing the previous value overwritten

replaceAsync

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

Asynchronous version of BasicCache.replace(Object, Object, long, TimeUnit). This method does not block on remote calls, even if your cache mode is synchronous.

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

CompletableFuture<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). This method does not block on remote calls, even if your cache mode is synchronous.

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

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

Asynchronous version of ConcurrentMap.replace(Object, Object, Object). This method does not block on remote calls, even if your cache mode is synchronous.

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

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

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.

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

CompletableFuture<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). This method does not block on remote calls, even if your cache mode is synchronous.

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

CompletableFuture<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. 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 to Map.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

default CompletableFuture<Boolean> containsKeyAsync(K key)

Asynchronous version of Map.containsKey(Object)

Parameters:

key - key to retrieve

Returns:

future containing true if the mapping exists.

getAllAsync

default CompletableFuture<Map<K,V>> getAllAsync(Set<?> keys)

computeAsync

CompletableFuture<V> computeAsync(K key,
                                  BiFunction<? super K,? super V,? extends V> remappingFunction)

Asynchronous version of ConcurrentMap.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 of BasicCache.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 of BasicCache.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

CompletableFuture<V> computeIfAbsentAsync(K key,
                                          Function<? super K,? extends V> mappingFunction)

Asynchronous version of ConcurrentMap.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 of BasicCache.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 of BasicCache.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 of ConcurrentMap.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 of BasicCache.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 of BasicCache.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 of ConcurrentMap.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 of BasicCache.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 of BasicCache.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