Module com.github.benmanes.caffeine

Package com.github.benmanes.caffeine.cache

Interface LoadingCache<K,V>

Type Parameters:

K - the type of keys maintained by this cache

V - the type of mapped values

All Superinterfaces:

Cache<K,V>

public interface LoadingCache<K,V>
extends Cache<K,V>

A semi-persistent mapping from keys to values. Values are automatically loaded by the cache, 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	Description
@Nullable V	get(K key)	Returns the value associated with the key in this cache, obtaining that value from CacheLoader.load(Object) if necessary.
Map<K,V>	getAll(Iterable<? extends K> keys)	Returns a map of the values associated with the keys, creating or retrieving those values if necessary.
CompletableFuture<V>	refresh(K key)	Loads a new value for the key, asynchronously.
CompletableFuture<Map<K,V>>	refreshAll(Iterable<? extends K> keys)	Loads a new value for each key, asynchronously.

Methods inherited from interface com.github.benmanes.caffeine.cache.Cache

asMap, cleanUp, estimatedSize, get, getAll, getAllPresent, getIfPresent, invalidate, invalidateAll, invalidateAll, policy, put, putAll, stats

Method Detail

get

@Nullable V get(K key)

Returns the value associated with the key in this cache, obtaining that value from CacheLoader.load(Object) if necessary.

If another call to get(K) is currently loading the value for the key, this thread simply waits for that thread to finish and returns its loaded value. Note that multiple threads can concurrently load values for distinct keys.

If the specified key is not already associated with a value, attempts to compute its value 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. Some attempted update operations on this cache by other threads may be blocked while the computation is in progress, so the computation should be short and simple, and must not attempt to update any other mappings of this cache.

Parameters:

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

Returns:

the current (existing or computed) value associated with the specified key, or null if the computed value is null

Throws:

NullPointerException - if the specified key is null

IllegalStateException - if the computation detectably attempts a recursive update to this cache that would otherwise never complete

CompletionException - if a checked exception was thrown while loading the value

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

getAll

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

Returns a map of the values associated with the keys, creating or retrieving those values if necessary. The returned map contains entries that were already cached, combined with the newly loaded entries; it will never contain null keys or values.

Caches loaded by a CacheLoader will issue a single request to CacheLoader.loadAll(java.util.Set<? extends K>) for all keys which are not already present in the cache. All entries returned by CacheLoader.loadAll(java.util.Set<? extends K>) will be stored in the cache, over-writing any previously cached values. If another call to get(K) tries to load the value for a key in keys, implementations may either have that thread load the entry or simply wait for this thread to finish and returns the loaded value. In the case of overlapping non-blocking loads, the last load to complete will replace the existing entry. 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 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

CompletionException - if a checked exception was thrown while loading the value

RuntimeException - or Error if the CacheLoader does so, if CacheLoader.loadAll(java.util.Set<? extends K>) returns null, returns a map containing null keys or values, or fails to return an entry for each requested key. In all cases, the mapping is left unestablished

refresh

CompletableFuture<V> refresh(K key)

Loads a new value for the key, asynchronously. While the new value is loading the previous value (if any) will continue to be returned by get(key) unless it is evicted. If the new value is loaded successfully it will replace the previous value in the cache; if an exception is thrown while refreshing the previous value will remain, and the exception will be logged (using System.Logger) and swallowed.

Caches loaded by a CacheLoader will call CacheLoader.reload(K, V) if the cache currently contains a value for the key, and CacheLoader.load(K) otherwise. Loading is asynchronous by delegating to the default executor.

Returns an existing future without doing anything if another thread is currently loading the value for key.

Parameters:

key - key with which a value may be associated

Returns:

the future that is loading the value

Throws:

NullPointerException - if the specified key is null

refreshAll

CompletableFuture<Map<K,V>> refreshAll(Iterable<? extends K> keys)

Loads a new value for each key, asynchronously. While the new value is loading the previous value (if any) will continue to be returned by get(key) unless it is evicted. If the new value is loaded successfully it will replace the previous value in the cache; if an exception is thrown while refreshing the previous value will remain, and the exception will be logged (using System.Logger) and swallowed. If another thread is currently loading the value for key, then does not perform an additional load.

Caches loaded by a CacheLoader will call CacheLoader.reload(K, V) if the cache currently contains a value for the key, and CacheLoader.load(K) otherwise. Loading is asynchronous by delegating to the default executor.

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 that are loading the values

Throws:

NullPointerException - if the specified collection is null or contains a null element