Module com.github.benmanes.caffeine

Package com.github.benmanes.caffeine.cache

Interface AsyncCacheLoader<K,V>

All Known Subinterfaces:

CacheLoader<K,V>

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface AsyncCacheLoader<K,V>

Computes or retrieves values asynchronously based on a key, for use in populating a AsyncLoadingCache.

Most implementations will only need to implement asyncLoad(K, java.util.concurrent.Executor). Other methods may be overridden as desired.

Usage example:

   AsyncCacheLoader<Key, Graph> loader = (key, executor) ->
       createExpensiveGraphAsync(key, executor);
   AsyncLoadingCache<Key, Graph> cache = Caffeine.newBuilder().buildAsync(loader);
 

Method Summary

Modifier and Type	Method	Description
CompletableFuture<? extends V>	asyncLoad(K key, Executor executor)	Asynchronously computes or retrieves the value corresponding to key.
default CompletableFuture<? extends Map<? extends K,? extends V>>	asyncLoadAll(Set<? extends K> keys, Executor executor)	Asynchronously computes or retrieves the values corresponding to keys.
default CompletableFuture<? extends V>	asyncReload(K key, V oldValue, Executor executor)	Asynchronously computes or retrieves a replacement value corresponding to an already-cached key.
static <K,V> AsyncCacheLoader<K,V>	bulk(BiFunction<? super Set<? extends K>,? super Executor,? extends CompletableFuture<? extends Map<? extends K,? extends V>>> mappingFunction)	Returns an asynchronous cache loader that delegates to the supplied mapping function for retrieving the values.
static <K,V> AsyncCacheLoader<K,V>	bulk(Function<? super Set<? extends K>,? extends Map<? extends K,? extends V>> mappingFunction)	Returns an asynchronous cache loader that delegates to the supplied mapping function for retrieving the values.

Method Detail

asyncLoad

CompletableFuture<? extends V> asyncLoad(K key,
                                         Executor executor)
                                  throws Exception

Asynchronously computes or retrieves the value corresponding to key.

Warning: loading must not attempt to update any mappings of this cache directly.

Parameters:

key - the non-null key whose value should be loaded

executor - the executor with which the entry may be asynchronously loaded with

Returns:

the future value associated with key

Throws:

Exception - or Error, in which case the mapping is unchanged

InterruptedException - if this method is interrupted. InterruptedException is treated like any other Exception in all respects except that, when it is caught, the thread's interrupt status is set

asyncLoadAll

default CompletableFuture<? extends Map<? extends K,? extends V>> asyncLoadAll(Set<? extends K> keys,
                                                                                     Executor executor)
                                                                              throws Exception

Asynchronously computes or retrieves the values corresponding to keys. This method is called by AsyncLoadingCache.getAll(java.lang.Iterable<? extends K>).

If the returned map doesn't contain all requested keys, then the entries it does contain will be cached, and getAll will return the partial results. If the returned map contains extra keys not present in keys, then all returned entries will be cached, but only the entries for keys will be returned from getAll.

This method should be overridden when bulk retrieval is significantly more efficient than many individual lookups. Note that AsyncLoadingCache.getAll(java.lang.Iterable<? extends K>) will defer to individual calls to AsyncLoadingCache.get(K) if this method is not overridden.

Warning: loading must not attempt to update any mappings of this cache directly.

Parameters:

keys - the unique, non-null keys whose values should be loaded

executor - the executor with which the entry may be asynchronously loaded with

Returns:

a future containing the map from each key in keys to the value associated with that key; may not contain null values

Throws:

Exception - or Error, in which case the mappings are unchanged

InterruptedException - if this method is interrupted. InterruptedException is treated like any other Exception in all respects except that, when it is caught, the thread's interrupt status is set

asyncReload

default CompletableFuture<? extends V> asyncReload(K key,
                                                   V oldValue,
                                                   Executor executor)
                                            throws Exception

Asynchronously computes or retrieves a replacement value corresponding to an already-cached key. If the replacement value is not found, then the mapping will be removed if null is computed. This method is called when an existing cache entry is refreshed by Caffeine.refreshAfterWrite(java.time.Duration), or through a call to LoadingCache.refresh(K).

Warning: loading must not attempt to update any mappings of this cache directly or block waiting for other cache operations to complete.

Note: all exceptions thrown by this method will be logged and then swallowed.

Parameters:

key - the non-null key whose value should be loaded

oldValue - the non-null old value corresponding to key

executor - the executor with which the entry may be asynchronously loaded with

Returns:

a future containing the new value associated with key, or containing null if the mapping is to be removed

Throws:

Exception - or Error, in which case the mapping is unchanged

InterruptedException - if this method is interrupted. InterruptedException is treated like any other Exception in all respects except that, when it is caught, the thread's interrupt status is set

bulk

static <K,V> AsyncCacheLoader<K,V> bulk(Function<? super Set<? extends K>,? extends Map<? extends K,? extends V>> mappingFunction)

Returns an asynchronous cache loader that delegates to the supplied mapping function for retrieving the values. Note that asyncLoad(K, java.util.concurrent.Executor) will discard any additional mappings loaded when retrieving the key prior to returning to the value to the cache.

Usage example:

   AsyncCacheLoader<Key, Graph> loader = AsyncCacheLoader.bulk(
       keys -> createExpensiveGraphs(keys));
   AsyncLoadingCache<Key, Graph> cache = Caffeine.newBuilder().buildAsync(loader);
 

Type Parameters:

K - the key type

V - the value type

Parameters:

mappingFunction - the function to asynchronously compute the values

Returns:

an asynchronous cache loader that delegates to the supplied mappingFunction

Throws:

NullPointerException - if the mappingFunction is null

bulk

static <K,V> AsyncCacheLoader<K,V> bulk(BiFunction<? super Set<? extends K>,? super Executor,? extends CompletableFuture<? extends Map<? extends K,? extends V>>> mappingFunction)

Returns an asynchronous cache loader that delegates to the supplied mapping function for retrieving the values. Note that asyncLoad(K, java.util.concurrent.Executor) will silently discard any additional mappings loaded when retrieving the key prior to returning to the value to the cache.

Usage example:

   AsyncCacheLoader<Key, Graph> loader = AsyncCacheLoader.bulk(
       (keys, executor) -> createExpensiveGraphs(keys, executor));
   AsyncLoadingCache<Key, Graph> cache = Caffeine.newBuilder().buildAsync(loader);
 

Type Parameters:

K - the key type

V - the value type

Parameters:

mappingFunction - the function to asynchronously compute the values

Returns:

an asynchronous cache loader that delegates to the supplied mappingFunction

Throws:

NullPointerException - if the mappingFunction is null