com.github.benmanes.caffeine.cache

Interface AsyncLoadingCache<K,V>

Type Parameters:

K - the type of keys maintained by this cache

V - the type of mapped values

@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

Modifier and Type	Method and Description
CompletableFuture<V>	get(K key) Returns the future associated with key in this cache, obtaining that value from CacheLoader.asyncLoad(K, java.util.concurrent.Executor) if necessary.
CompletableFuture<V>	get(K key, BiFunction<? super K,Executor,CompletableFuture<V>> mappingFunction) Returns the future associated with key in this cache, obtaining that value from mappingFunction if necessary.
CompletableFuture<V>	get(K key, Function<? super K,? extends V> mappingFunction) Returns the future associated with key in this cache, obtaining that value from mappingFunction if necessary.
CompletableFuture<Map<K,V>>	getAll(Iterable<? extends K> keys) Returns the future of a map of the values associated with keys, creating or retrieving those values if necessary.
CompletableFuture<V>	getIfPresent(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, CompletableFuture<V> valueFuture) Associates value with key in this cache.
LoadingCache<K,V>	synchronous() Returns a view of the entries stored in this cache as a synchronous LoadingCache.

Method Detail

getIfPresent

@CheckForNull
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.

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:

NullPointerException - if the specified key is null

get

@Nonnull
CompletableFuture<V> get(@Nonnull
                                  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. 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.

Parameters:

key - key with which the specified value is to be associated

mappingFunction - the function to asynchronously compute a value

Returns:

the current (existing or computed) future value associated with the specified key

Throws:

NullPointerException - if the specified key or mappingFunction is null

get

@Nonnull
CompletableFuture<V> get(@Nonnull
                                  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. 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.

Parameters:

key - key with which the specified value is to be associated

mappingFunction - the function to asynchronously compute a value

Returns:

the current (existing or computed) future value associated with the specified key

Throws:

NullPointerException - if the specified key or mappingFunction is null, or if the future returned by the mappingFunction is null

RuntimeException - or Error if the mappingFunction does when constructing the future, in which case the mapping is left unestablished

get

@Nonnull
CompletableFuture<V> get(@Nonnull
                                  K key)

Returns the future associated with key in this cache, obtaining that value from CacheLoader.asyncLoad(K, java.util.concurrent.Executor) if necessary. If the asynchronous computation fails, the entry will be automatically removed from this cache.

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:

NullPointerException - if the specified key is null or if the future returned by the AsyncCacheLoader is null

RuntimeException - or Error if the CacheLoader does when constructing the future, in which case the mapping is left unestablished

getAll

@Nonnull
CompletableFuture<Map<K,V>> getAll(@Nonnull
                                            Iterable<? extends K> keys)

Returns the future of a map of the values associated with 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.

Caches loaded by a CacheLoader supporting bulk loading will issue a single request to CacheLoader.asyncLoadAll(java.lang.Iterable<? extends K>, java.util.concurrent.Executor) 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 simply waits for this computation to finish and returns the loaded value. Caches that do not use a CacheLoader with an optimized bulk load implementation will sequentially load each key by making individual CacheLoader.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 by Object.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:

NullPointerException - if the specified collection is null or contains a null element, or if the future returned by the AsyncCacheLoader is null

RuntimeException - or Error if the CacheLoader does so, if CacheLoader.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 unestablished

put

void put(@Nonnull
         K key,
         @Nonnull
         CompletableFuture<V> valueFuture)

Associates 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.

Parameters:

key - key with which the specified value is to be associated

valueFuture - value to be associated with the specified key

Throws:

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 synchronous LoadingCache. 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