Interface AsyncLoadingCache<K,V>
-
- Type Parameters:
K
- the type of keys maintained by this cacheV
- the type of mapped values
- All Known Implementing Classes:
BoundedLocalCache.BoundedLocalAsyncLoadingCache
,LocalAsyncLoadingCache
,UnboundedLocalCache.UnboundedLocalAsyncLoadingCache
@ThreadSafe public interface AsyncLoadingCache<K,V>
A semi-persistent mapping from keys to values. Values are automatically loaded by the cache asynchronously, 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.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description java.util.concurrent.CompletableFuture<V>
get(K key)
Returns the future associated withkey
in this cache, obtaining that value fromCacheLoader.asyncLoad(K, java.util.concurrent.Executor)
if necessary.java.util.concurrent.CompletableFuture<V>
get(K key, java.util.function.BiFunction<? super K,java.util.concurrent.Executor,java.util.concurrent.CompletableFuture<V>> mappingFunction)
Returns the future associated withkey
in this cache, obtaining that value frommappingFunction
if necessary.java.util.concurrent.CompletableFuture<V>
get(K key, java.util.function.Function<? super K,? extends V> mappingFunction)
Returns the future associated withkey
in this cache, obtaining that value frommappingFunction
if necessary.java.util.concurrent.CompletableFuture<java.util.Map<K,V>>
getAll(java.lang.Iterable<? extends K> keys)
Returns the future of a map of the values associated withkeys
, creating or retrieving those values if necessary.java.util.concurrent.CompletableFuture<V>
getIfPresent(java.lang.Object key)
Returns the future associated withkey
in this cache, ornull
if there is no cached future forkey
.void
put(K key, java.util.concurrent.CompletableFuture<V> valueFuture)
Associatesvalue
withkey
in this cache.LoadingCache<K,V>
synchronous()
Returns a view of the entries stored in this cache as a synchronousLoadingCache
.
-
-
-
Method Detail
-
getIfPresent
@CheckForNull java.util.concurrent.CompletableFuture<V> getIfPresent(@Nonnull java.lang.Object key)
Returns the future associated withkey
in this cache, ornull
if there is no cached future forkey
.- Parameters:
key
- key whose associated value is to be returned- Returns:
- the current (existing or computed) future value to which the specified key is mapped,
or
null
if this map contains no mapping for the key - Throws:
java.lang.NullPointerException
- if the specified key is null
-
get
@Nonnull java.util.concurrent.CompletableFuture<V> get(@Nonnull K key, @Nonnull java.util.function.Function<? super K,? extends V> mappingFunction)
Returns the future associated withkey
in this cache, obtaining that value frommappingFunction
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.Warning: as with
CacheLoader.load(K)
,mappingFunction
must not attempt to update any other mappings of this cache.- Parameters:
key
- key with which the specified value is to be associatedmappingFunction
- the function to asynchronously compute a value- Returns:
- the current (existing or computed) future value associated with the specified key
- Throws:
java.lang.NullPointerException
- if the specified key or mappingFunction is null
-
get
@Nonnull java.util.concurrent.CompletableFuture<V> get(@Nonnull K key, @Nonnull java.util.function.BiFunction<? super K,java.util.concurrent.Executor,java.util.concurrent.CompletableFuture<V>> mappingFunction)
Returns the future associated withkey
in this cache, obtaining that value frommappingFunction
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.Warning: as with
CacheLoader.load(K)
,mappingFunction
must not attempt to update any other mappings of this cache.- Parameters:
key
- key with which the specified value is to be associatedmappingFunction
- the function to asynchronously compute a value- Returns:
- the current (existing or computed) future value associated with the specified key
- Throws:
java.lang.NullPointerException
- if the specified key or mappingFunction is nulljava.lang.RuntimeException
- or Error if the mappingFunction does when constructing the future, in which case the mapping is left unestablished
-
get
@Nonnull java.util.concurrent.CompletableFuture<V> get(@Nonnull K key)
Returns the future associated withkey
in this cache, obtaining that value fromCacheLoader.asyncLoad(K, java.util.concurrent.Executor)
if necessary. If the asynchronous computation fails, the entry will be automatically removed.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.- Parameters:
key
- key with which the specified value is to be associated- Returns:
- the current (existing or computed) future value associated with the specified key
- Throws:
java.lang.NullPointerException
- if the specified key is nulljava.lang.RuntimeException
- or Error if theCacheLoader
does when constructing the future, in which case the mapping is left unestablished
-
getAll
@Nonnull java.util.concurrent.CompletableFuture<java.util.Map<K,V>> getAll(@Nonnull java.lang.Iterable<? extends K> keys)
Returns the future of a map of the values associated withkeys
, 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.Caches loaded by a
CacheLoader
supporting bulk loading will issue a single request toCacheLoader.asyncLoadAll(java.lang.Iterable<? extends K>, java.util.concurrent.Executor)
for all keys which are not already present in the cache. If another call toget(K, java.util.function.Function<? super K, ? extends V>)
tries to load the value for a key inkeys
, that thread simply waits for this computation to finish and returns the loaded value. Caches that do not use aCacheLoader
with an optimized bulk load implementation will sequentially load each key by making individualCacheLoader.asyncLoad(K, java.util.concurrent.Executor)
calls. Note that multiple threads can concurrently load values for distinct keys.Note that duplicate elements in
keys
, as determined byObject.equals(java.lang.Object)
, will be ignored.- Parameters:
keys
- the keys whose associated values are to be returned- Returns:
- the future containing an unmodifiable mapping of keys to values for the specified keys in this cache
- Throws:
java.lang.NullPointerException
- if the specified collection is null or contains a null elementjava.lang.RuntimeException
- or Error if theCacheLoader
does so, ifCacheLoader.asyncLoadAll(java.lang.Iterable<? extends K>, java.util.concurrent.Executor)
returnsnull
, or fails when constructing the future, in which case the mapping is left unestablished
-
put
void put(@Nonnull K key, @Nonnull java.util.concurrent.CompletableFuture<V> valueFuture)
Associatesvalue
withkey
in this cache. If the cache previously contained a value associated withkey
, the old value is replaced byvalue
. 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.- Parameters:
key
- key with which the specified value is to be associatedvalueFuture
- value to be associated with the specified key- Throws:
java.lang.NullPointerException
- if the specified key or value is null
-
synchronous
@Nonnull LoadingCache<K,V> synchronous()
Returns a view of the entries stored in this cache as a synchronousLoadingCache
. 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.- Returns:
- a thread-safe synchronous view of this cache
-
-