Interface LoadingCache<K,V>
-
- Type Parameters:
K
- the type of the cache's keys, which are not permitted to be nullV
- the type of the cache's values, which are not permitted to be null
- All Known Implementing Classes:
AbstractLoadingCache
,ForwardingLoadingCache
,ForwardingLoadingCache.SimpleForwardingLoadingCache
@GwtCompatible public interface LoadingCache<K,V> extends Cache<K,V>, Function<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. The common way to build instances is usingCacheBuilder
.Implementations of this interface are expected to be thread-safe, and can be safely accessed by multiple concurrent threads.
When evaluated as a
Function
, a cache yields the same result as invokinggetUnchecked(K)
.- Since:
- 11.0
- Author:
- Charles Fry
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description V
apply(K key)
Deprecated.java.util.concurrent.ConcurrentMap<K,V>
asMap()
Returns a view of the entries stored in this cache as a thread-safe map.V
get(K key)
Returns the value associated withkey
in this cache, first loading that value if necessary.ImmutableMap<K,V>
getAll(java.lang.Iterable<? extends K> keys)
Returns a map of the values associated withkeys
, creating or retrieving those values if necessary.V
getUnchecked(K key)
Returns the value associated withkey
in this cache, first loading that value if necessary.void
refresh(K key)
Loads a new value forkey
, possibly asynchronously.-
Methods inherited from interface com.google.common.cache.Cache
cleanUp, get, getAllPresent, getIfPresent, invalidate, invalidateAll, invalidateAll, put, putAll, size, stats
-
-
-
-
Method Detail
-
get
@CanIgnoreReturnValue V get(K key) throws java.util.concurrent.ExecutionException
Returns the value associated withkey
in this cache, first loading that value if necessary. No observable state associated with this cache is modified until loading completes.If another call to
get(K)
orgetUnchecked(K)
is currently loading the value forkey
, simply waits for that thread to finish and returns its loaded value. Note that multiple threads can concurrently load values for distinct keys.Caches loaded by a
CacheLoader
will callCacheLoader.load(K)
to load new values into the cache. Newly loaded values are added to the cache usingCache.asMap().putIfAbsent
after loading has completed; if another value was associated withkey
while the new value was loading then a removal notification will be sent for the new value.If the cache loader associated with this cache is known not to throw checked exceptions, then prefer
getUnchecked(K)
over this method.- Throws:
java.util.concurrent.ExecutionException
- if a checked exception was thrown while loading the value. (ExecutionException
is thrown even if computation was interrupted by anInterruptedException
.)UncheckedExecutionException
- if an unchecked exception was thrown while loading the valueExecutionError
- if an error was thrown while loading the value
-
getUnchecked
@CanIgnoreReturnValue V getUnchecked(K key)
Returns the value associated withkey
in this cache, first loading that value if necessary. No observable state associated with this cache is modified until loading completes. Unlikeget(K)
, this method does not throw a checked exception, and thus should only be used in situations where checked exceptions are not thrown by the cache loader.If another call to
get(K)
orgetUnchecked(K)
is currently loading the value forkey
, simply waits for that thread to finish and returns its loaded value. Note that multiple threads can concurrently load values for distinct keys.Caches loaded by a
CacheLoader
will callCacheLoader.load(K)
to load new values into the cache. Newly loaded values are added to the cache usingCache.asMap().putIfAbsent
after loading has completed; if another value was associated withkey
while the new value was loading then a removal notification will be sent for the new value.Warning: this method silently converts checked exceptions to unchecked exceptions, and should not be used with cache loaders which throw checked exceptions. In such cases use
get(K)
instead.- Throws:
UncheckedExecutionException
- if an exception was thrown while loading the value. (As explained in the last paragraph above, this should be an unchecked exception only.)ExecutionError
- if an error was thrown while loading the value
-
getAll
@CanIgnoreReturnValue ImmutableMap<K,V> getAll(java.lang.Iterable<? extends K> keys) throws java.util.concurrent.ExecutionException
Returns 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.Caches loaded by a
CacheLoader
will issue a single request toCacheLoader.loadAll(java.lang.Iterable<? extends K>)
for all keys which are not already present in the cache. All entries returned byCacheLoader.loadAll(java.lang.Iterable<? extends K>)
will be stored in the cache, over-writing any previously cached values. This method will throw an exception ifCacheLoader.loadAll(java.lang.Iterable<? extends K>)
returnsnull
, returns a map containing null keys or values, or fails to return an entry for each requested key.Note that duplicate elements in
keys
, as determined byObject.equals(java.lang.Object)
, will be ignored.- Throws:
java.util.concurrent.ExecutionException
- if a checked exception was thrown while loading the value. (ExecutionException
is thrown even if computation was interrupted by anInterruptedException
.)UncheckedExecutionException
- if an unchecked exception was thrown while loading the valuesExecutionError
- if an error was thrown while loading the values- Since:
- 11.0
-
apply
@Deprecated V apply(K key)
Deprecated.- Specified by:
apply
in interfaceFunction<K,V>
- Specified by:
apply
in interfacejava.util.function.Function<K,V>
- Throws:
UncheckedExecutionException
- if an exception was thrown while loading the value. (As described in the documentation forgetUnchecked(K)
,LoadingCache
should be used as aFunction
only with cache loaders that throw only unchecked exceptions.)
-
refresh
void refresh(K key)
Loads a new value forkey
, possibly asynchronously. While the new value is loading the previous value (if any) will continue to be returned byget(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 (usingLogger
) and swallowed.Caches loaded by a
CacheLoader
will callCacheLoader.reload(K, V)
if the cache currently contains a value forkey
, andCacheLoader.load(K)
otherwise. Loading is asynchronous only ifCacheLoader.reload(K, V)
was overridden with an asynchronous implementation.Returns without doing anything if another thread is currently loading the value for
key
. If the cache loader associated with this cache performs refresh asynchronously then this method may return before refresh completes.- Since:
- 11.0
-
asMap
java.util.concurrent.ConcurrentMap<K,V> asMap()
Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to the map directly affect the 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.
Note that although the view is modifiable, no method on the returned map will ever cause entries to be automatically loaded.
-
-