com.google.common.cache
Interface Cache<K,V>

All Superinterfaces:

Function<K,V>

All Known Implementing Classes:

AbstractCache, ForwardingCache, ForwardingCache.SimpleForwardingCache

@Beta
public interface Cache<K,V>
extends 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.

All methods other than get(K) and getUnchecked(K) are optional.

When evaluated as a Function, a cache yields the same result as invoking getUnchecked(K).

Since:

10.0

Author:

Charles Fry

Method Summary

ImmutableList<Map.Entry<K,V>>	activeEntries(int limit) Returns a list of immutable copies of this cache's most active entries, approximately ordered from least likely to be evicted to most likely to be evicted.
V	apply(K key) Discouraged.
ConcurrentMap<K,V>	asMap() Returns a view of the entries stored in this cache as a thread-safe map.
void	cleanUp() Performs any pending maintenance operations needed by the cache.
V	get(K key) Returns the value associated with the given key, creating or retrieving that value if necessary, and throwing an execution exception on failure.
V	getUnchecked(K key) Returns the value associated with the given key, loading that value if necessary.
void	invalidate(Object key) Discards any cached value for key key, possibly asynchronously, so that a future invocation of get(key) will result in a cache miss and reload.
void	invalidateAll() Discards all entries in the cache, possibly asynchronously.
int	size() Returns the approximate number of entries in this cache.
CacheStats	stats() Returns a current snapshot of this cache's cumulative statistics.

Methods inherited from interface com.google.common.base.Function

equals

Method Detail

get

@Nullable
V get(K key)
      throws ExecutionException

Returns the value associated with the given key, creating or retrieving that value if necessary, and throwing an execution exception on failure. No state associated with this cache is modified until loading completes.

The implementation may support null as a valid cached value, or may return null without caching it, or may not permit null results at all.

Throws:

ExecutionException - if a checked exception was thrown while loading the response

UncheckedExecutionException - if an unchecked exception was thrown while loading the response

ExecutionError - if an error was thrown while loading the response

getUnchecked

@Nullable
V getUnchecked(K key)

Returns the value associated with the given key, loading that value if necessary. No state associated with this cache is modified until computation completes. Unlike get(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.

Warning: this method silently converts checked exceptions to unchecked exceptions. The get(K) method should be preferred for cache loaders which throw checked exceptions.

The implementation may support null as a valid cached value, or may return null without caching it, or may not permit null results at all.

Throws:

UncheckedExecutionException - if an exception was thrown while loading the response, regardless of whether the exception was checked or unchecked

ExecutionError - if an error was thrown while loading the response

apply

@Nullable
V apply(K key)

Discouraged. Provided to satisfy the Function interface; use get(K) or getUnchecked(K) instead.

Specified by:

apply in interface Function<K,V>

Throws:

UncheckedExecutionException - if an exception was thrown while loading the response, regardless of whether the exception was checked or unchecked

ExecutionError - if an error was thrown while loading the response

invalidate

void invalidate(@Nullable
                Object key)

Discards any cached value for key key, possibly asynchronously, so that a future invocation of get(key) will result in a cache miss and reload.

Throws:

UnsupportedOperationException - if this operation is not supported by the cache implementation

invalidateAll

void invalidateAll()

Discards all entries in the cache, possibly asynchronously.

Throws:

UnsupportedOperationException - if this operation is not supported by the cache implementation

size

int size()

Returns the approximate number of entries in this cache. If the cache contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Throws:

UnsupportedOperationException - if this operation is not supported by the cache implementation

stats

CacheStats stats()

Returns a current snapshot of this cache's cumulative statistics. All stats are initialized to zero, and are monotonically increasing over the lifetime of the cache.

Throws:

UnsupportedOperationException - if this operation is not supported by the cache implementation

activeEntries

ImmutableList<Map.Entry<K,V>> activeEntries(int limit)

Returns a list of immutable copies of this cache's most active entries, approximately ordered from least likely to be evicted to most likely to be evicted.

Parameters:

limit - the maximum number of entries to return

Throws:

UnsupportedOperationException - if this operation is not supported by the cache implementation

asMap

ConcurrentMap<K,V> asMap()

Returns a view of the entries stored in this cache as a thread-safe map. Assume that none of the returned map's optional operations will be implemented, unless otherwise specified.

Operations on the returned map will never cause new values to be loaded into the cache. So, unlike get(K) and getUnchecked(K), this map's get method will always return null for a key that is not already cached.

Throws:

UnsupportedOperationException - if this operation is not supported by the cache implementation

cleanUp

void cleanUp()

Performs any pending maintenance operations needed by the cache. Exactly which activities are performed -- if any -- is implementation-dependent.