Guava: Google Core Libraries for Java 33.1.0-jre · com.google.common.cache.Cache

Method Summary

Modifier and Type	Method and Description
public ConcurrentMap<K, V>	asMap() Returns a view of the entries stored in this cache as a thread-safe map.
public void	cleanUp() Performs any pending maintenance operations needed by the cache.
public V	get(K key, Callable<? extends V> loader) Returns the value associated with `key` in this cache, obtaining that value from `loader` if necessary.
public ImmutableMap<K, V>	getAllPresent(Iterable<? extends Object> keys) Returns a map of the values associated with `keys` in this cache.
public V	getIfPresent(Object key) Returns the value associated with `key` in this cache, or `null` if there is no cached value for `key`.
public void	invalidate(Object key) Discards any cached value for key `key`.
public void	invalidateAll(Iterable<? extends Object> keys) Discards any cached values for keys `keys`.
public void	invalidateAll() Discards all entries in the cache.
public void	put(K key, V value) Associates `value` with `key` in this cache.
public void	putAll(Map<? extends K, ? extends V> m) Copies all of the mappings from the specified map to the cache.
public long	size() Returns the approximate number of entries in this cache.
public CacheStats	stats() Returns a current snapshot of this cache's cumulative statistics, or a set of default values if the cache is not recording statistics.

Method Detail

asMap	back to summary
public 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.

asMap

back to summary

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

cleanUp	back to summary
public void cleanUp() Performs any pending maintenance operations needed by the cache. Exactly which activities are performed -- if any -- is implementation-dependent.

get back to summary

get	back to summary
public V get(K key, Callable<? extends V> loader) throws ExecutionException Returns the value associated with `key` in this cache, obtaining that value from `loader` if necessary. The method improves upon the conventional "if cached, return; otherwise create, cache and return" pattern. For further improvements, use `LoadingCache` and its `get(K)` method instead of this one. Among the improvements that this method and `LoadingCache.get(K)` both provide are: awaiting the result of a pending load rather than starting a redundant one eliminating the error-prone caching boilerplate tracking load statistics Among the further improvements that `LoadingCache` can provide but this method cannot: consolidation of the loader logic to a single authoritative location refreshing of entries, including automated refreshing bulk loading requests, including bulk loading implementations Warning For any given key, every `loader` used with it should compute the same value. Otherwise, a call that passes one `loader` may return the result of another call with a differently behaving `loader`. For example, a call that requests a short timeout for an RPC may wait for a similar call that requests a long timeout, or a call by an unprivileged user may return a resource accessible only to a privileged user making a similar call. To prevent this problem, create a key object that includes all values that affect the result of the query. Or use `LoadingCache.get(K)`, which lacks the ability to refer to state other than that in the key. Warning as with `CacheLoader#load`, `loader` must not return `null`; it may either return a non-null value or throw an exception. No observable state associated with this cache is modified until loading completes. Annotations @CanIgnoreReturnValue Exceptions ExecutionException: if a checked exception was thrown while loading the value UncheckedExecutionException: if an unchecked exception was thrown while loading the value ExecutionError: if an error was thrown while loading the value Since 11.0

public V get(K key, Callable<? extends V> loader) throws ExecutionException

Returns the value associated with key in this cache, obtaining that value from loader if necessary. The method improves upon the conventional "if cached, return; otherwise create, cache and return" pattern. For further improvements, use LoadingCache and its get(K) method instead of this one.

Among the improvements that this method and LoadingCache.get(K) both provide are:

awaiting the result of a pending load rather than starting a redundant one
eliminating the error-prone caching boilerplate
tracking load statistics

Among the further improvements that LoadingCache can provide but this method cannot:

consolidation of the loader logic to a single authoritative location
refreshing of entries, including automated refreshing
bulk loading requests, including bulk loading implementations

Warning

For any given key, every loader used with it should compute the same value. Otherwise, a call that passes one loader may return the result of another call with a differently behaving loader. For example, a call that requests a short timeout for an RPC may wait for a similar call that requests a long timeout, or a call by an unprivileged user may return a resource accessible only to a privileged user making a similar call. To prevent this problem, create a key object that includes all values that affect the result of the query. Or use LoadingCache.get(K), which lacks the ability to refer to state other than that in the key.

Warning

as with CacheLoader#load, loader must not return null; it may either return a non-null value or throw an exception.

No observable state associated with this cache is modified until loading completes.

Annotations

@CanIgnoreReturnValue

Exceptions

ExecutionException:: if a checked exception was thrown while loading the value
UncheckedExecutionException:: if an unchecked exception was thrown while loading the value
ExecutionError:: if an error was thrown while loading the value

Since

11.0

getAllPresent back to summary

getAllPresent	back to summary
public ImmutableMap<K, V> getAllPresent(Iterable<? extends Object> keys) Returns a map of the values associated with `keys` in this cache. The returned map will only contain entries which are already present in the cache. Since 11.0

public ImmutableMap<K, V> getAllPresent(Iterable<? extends Object> keys)

Returns a map of the values associated with keys in this cache. The returned map will only contain entries which are already present in the cache.

Since: 11.0

getIfPresent back to summary

getIfPresent	back to summary
public V getIfPresent(Object key) Returns the value associated with `key` in this cache, or `null` if there is no cached value for `key`. Annotations @CheckForNull @CanIgnoreReturnValue Since 11.0

public V getIfPresent(Object key)

Returns the value associated with key in this cache, or null if there is no cached value for key.

Annotations

@CheckForNull
@CanIgnoreReturnValue

Since

11.0

invalidate	back to summary
public void invalidate(Object key) Discards any cached value for key `key`.

invalidateAll back to summary

invalidateAll	back to summary
public void invalidateAll(Iterable<? extends Object> keys) Discards any cached values for keys `keys`. Since 11.0

public void invalidateAll(Iterable<? extends Object> keys)

Discards any cached values for keys keys.

Since: 11.0

invalidateAll	back to summary
public void invalidateAll() Discards all entries in the cache.

put back to summary

put	back to summary
public void put(K key, V value) Associates `value` with `key` in this cache. If the cache previously contained a value associated with `key`, the old value is replaced by `value`. Prefer `get(Object, Callable)` when using the conventional "if cached, return; otherwise create, cache and return" pattern. Since 11.0

public void put(K key, V value)

Associates value with key in this cache. If the cache previously contained a value associated with key, the old value is replaced by value.

Prefer get(Object, Callable) when using the conventional "if cached, return; otherwise create, cache and return" pattern.

Since: 11.0

putAll back to summary

putAll	back to summary
public void putAll(Map<? extends K, ? extends V> m) Copies all of the mappings from the specified map to the cache. The effect of this call is equivalent to that of calling `put(k, v)` on this map once for each mapping from key `k` to value `v` in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress. Since 12.0

public void putAll(Map<? extends K, ? extends V> m)

Copies all of the mappings from the specified map to the cache. The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress.

Since: 12.0

size	back to summary
public long size() Returns the approximate number of entries in this cache.

stats	back to summary
public CacheStats stats() Returns a current snapshot of this cache's cumulative statistics, or a set of default values if the cache is not recording statistics. All statistics begin at zero and never decrease over the lifetime of the cache. Warning this cache may not be recording statistical data. For example, a cache created using `CacheBuilder` only does so if the `CacheBuilder#recordStats` method was called. If statistics are not being recorded, a `CacheStats` instance with zero for all values is returned.

public Interface Cache<K, V>

Method Summary

Method Detail