K
- the type of keys maintained by this cacheV
- the type of mapped valuespublic interface AsyncCache<K,V>
get(Object, Function)
or put(Object, CompletableFuture)
, and are stored in the
cache until either evicted or manually invalidated.
Implementations of this interface are expected to be thread-safe, and can be safely accessed by multiple concurrent threads.
Modifier and Type | Method and Description |
---|---|
@NonNull ConcurrentMap<K,CompletableFuture<V>> |
asMap()
Returns a view of the entries stored in this cache as a thread-safe map.
|
@NonNull CompletableFuture<V> |
get(K key,
@NonNull BiFunction<? super K,Executor,CompletableFuture<V>> mappingFunction)
Returns the future associated with
key in this cache, obtaining that value from
mappingFunction if necessary. |
@NonNull CompletableFuture<V> |
get(K key,
@NonNull Function<? super K,? extends V> mappingFunction)
Returns the future associated with
key in this cache, obtaining that value from
mappingFunction if necessary. |
default @NonNull CompletableFuture<Map<K,V>> |
getAll(@NonNull Iterable<? extends K> keys,
@NonNull BiFunction<Iterable<? extends K>,Executor,CompletableFuture<Map<K,V>>> mappingFunction)
Returns the future of a map of the values associated with
keys , creating or retrieving
those values if necessary. |
default @NonNull CompletableFuture<Map<K,V>> |
getAll(@NonNull Iterable<? extends K> keys,
@NonNull Function<Iterable<? extends K>,Map<K,V>> mappingFunction)
Returns the future of a map of the values associated with
keys , creating or retrieving
those values if necessary. |
@Nullable CompletableFuture<V> |
getIfPresent(@NonNull Object key)
Returns the future associated with
key in this cache, or null if there is no
cached future for key . |
void |
put(K key,
@NonNull CompletableFuture<V> valueFuture)
Associates
value with key in this cache. |
@NonNull Cache<K,V> |
synchronous()
Returns a view of the entries stored in this cache as a synchronous
Cache . |
@Nullable CompletableFuture<V> getIfPresent(@CompatibleWith(value="K") @NonNull Object key)
key
in this cache, or null
if there is no
cached future for key
.key
- key whose associated value is to be returnednull
if this map contains no mapping for the keyNullPointerException
- if the specified key is null@NonNull CompletableFuture<V> get(K key, @NonNull Function<? super K,? extends V> mappingFunction)
key
in this cache, obtaining that value from
mappingFunction
if necessary. This method provides a simple substitute for the
conventional "if cached, return; otherwise create, cache and return" pattern.
If the specified key is not already associated with a value, attempts to compute its value
asynchronously and enters it into this cache unless null
. The entire method invocation
is performed atomically, so the function is applied at most once per key. If the asynchronous
computation fails, the entry will be automatically removed from this cache.
Warning: as with CacheLoader.load(K)
, mappingFunction
must not
attempt to update any other mappings of this cache.
key
- key with which the specified value is to be associatedmappingFunction
- the function to asynchronously compute a valueNullPointerException
- if the specified key or mappingFunction is null@NonNull CompletableFuture<V> get(K key, @NonNull BiFunction<? super K,Executor,CompletableFuture<V>> mappingFunction)
key
in this cache, obtaining that value from
mappingFunction
if necessary. This method provides a simple substitute for the
conventional "if cached, return; otherwise create, cache and return" pattern.
If the specified key is not already associated with a value, attempts to compute its value
asynchronously and enters it into this cache unless null
. The entire method invocation
is performed atomically, so the function is applied at most once per key. If the asynchronous
computation fails, the entry will be automatically removed from this cache.
Warning: as with CacheLoader.load(K)
, mappingFunction
must not
attempt to update any other mappings of this cache.
key
- key with which the specified value is to be associatedmappingFunction
- the function to asynchronously compute a valueNullPointerException
- if the specified key or mappingFunction is null, or if the
future returned by the mappingFunction is nullRuntimeException
- or Error if the mappingFunction does when constructing the future,
in which case the mapping is left unestablisheddefault @NonNull CompletableFuture<Map<K,V>> getAll(@NonNull Iterable<? extends K> keys, @NonNull Function<Iterable<? extends K>,Map<K,V>> mappingFunction)
keys
, creating or retrieving
those values if necessary. The returned map contains entries that were already cached, combined
with newly loaded entries; it will never contain null keys or values. If the any of the
asynchronous computations fail, those entries will be automatically removed from this cache.
A single request to the mappingFunction
is performed for all keys which are not already
present in the cache. If another call to get(K, java.util.function.Function<? super K, ? extends V>)
tries to load the value for a key in
keys
, that thread retrieves a future that is completed by this bulk computation. Note
that multiple threads can concurrently load values for distinct keys.
Note that duplicate elements in keys
, as determined by Object.equals(java.lang.Object)
, will be
ignored.
keys
- the keys whose associated values are to be returnedmappingFunction
- the function to asynchronously compute the valuesNullPointerException
- if the specified collection is null or contains a null element, or
if the future returned by the AsyncCacheLoader
is nullRuntimeException
- or Error if the AsyncCacheLoader
does so, if
AsyncCacheLoader.asyncLoadAll(java.lang.Iterable<? extends K>, java.util.concurrent.Executor)
returns null
, or fails when constructing
the future, in which case the mapping is left unestablisheddefault @NonNull CompletableFuture<Map<K,V>> getAll(@NonNull Iterable<? extends K> keys, @NonNull BiFunction<Iterable<? extends K>,Executor,CompletableFuture<Map<K,V>>> mappingFunction)
keys
, creating or retrieving
those values if necessary. The returned map contains entries that were already cached, combined
with newly loaded entries; it will never contain null keys or values. If the any of the
asynchronous computations fail, those entries will be automatically removed from this cache.
A single request to the mappingFunction
is performed for all keys which are not already
present in the cache. If another call to get(K, java.util.function.Function<? super K, ? extends V>)
tries to load the value for a key in
keys
, that thread retrieves a future that is completed by this bulk computation. Note
that multiple threads can concurrently load values for distinct keys.
Note that duplicate elements in keys
, as determined by Object.equals(java.lang.Object)
, will be
ignored.
keys
- the keys whose associated values are to be returnedmappingFunction
- the function to asynchronously compute the valuesNullPointerException
- if the specified collection is null or contains a null element, or
if the future returned by the AsyncCacheLoader
is nullRuntimeException
- or Error if the AsyncCacheLoader
does so, if
AsyncCacheLoader.asyncLoadAll(java.lang.Iterable<? extends K>, java.util.concurrent.Executor)
returns null
, or fails when constructing
the future, in which case the mapping is left unestablishedvoid put(K key, @NonNull CompletableFuture<V> valueFuture)
value
with key
in this cache. If the cache previously contained a
value associated with key
, the old value is replaced by value
. If the
asynchronous computation fails, the entry will be automatically removed.
Prefer get(Object, Function)
when using the conventional "if cached, return; otherwise
create, cache and return" pattern.
key
- key with which the specified value is to be associatedvalueFuture
- value to be associated with the specified keyNullPointerException
- if the specified key or value is null@NonNull ConcurrentMap<K,CompletableFuture<V>> asMap()
A computation operation, such as ConcurrentMap.compute(K, java.util.function.BiFunction<? super K, ? super V, ? extends V>)
, performs the entire method
invocation atomically, so the function is applied at most once per key. Some attempted update
operations by other threads may be blocked while computation is in progress. The computation
must not attempt to update any other mappings of this cache.
Iterators from the returned map are at least weakly consistent: they are safe for concurrent use, but if the cache is modified (including by eviction) after the iterator is created, it is undefined which of the changes (if any) will be reflected in that iterator.
Map
operations@NonNull Cache<K,V> synchronous()
Cache
. A mapping is
not present if the value is currently being loaded. Modifications made to the synchronous cache
directly affect the asynchronous cache. If a modification is made to a mapping that is
currently loading, the operation blocks until the computation completes.