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

All Known Subinterfaces:
  LoadingCache<K,V>

All Known Implementing Classes:
  AbstractCache, AbstractLoadingCache, ForwardingCache, ForwardingCache.SimpleForwardingCache, ForwardingLoadingCache, ForwardingLoadingCache.SimpleForwardingLoadingCache

    @Beta
    @GwtCompatible
    public interface Cache<K,V>

A semi-persistent mapping from keys to values. Cache entries are manually added using `get(Object, Callable)` or `put(Object, Object)`, 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.

Note that while this class is still annotated as `Beta`, the API is frozen from a consumer's standpoint. In other words existing methods are all considered `non-Beta` and won't be changed without going through an 18 month deprecation cycle; however new methods may be added at any time.

Since:
  10.0
Author:
  Charles Fry

Method Summary
`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, Callable<? extends V> valueLoader)` Returns the value associated with `key` in this cache, obtaining that value from `valueLoader` if necessary.
`ImmutableMap<K,V>` `getAllPresent(Iterable<?> keys)` Returns a map of the values associated with `keys` in this cache.
`V` `getIfPresent(Object key)` Returns the value associated with `key` in this cache, or `null` if there is no cached value for `key`.
`void` `invalidate(Object key)` Discards any cached value for key `key`.
`void` `invalidateAll()` Discards all entries in the cache.
`void` `invalidateAll(Iterable<?> keys)` Discards any cached values for keys `keys`.
`void` `put(K key, V value)` Associates `value` with `key` in this cache.
`void` `putAll(Map<? extends K,? extends V> m)` Copies all of the mappings from the specified map to the cache.
`long` `size()` Returns the approximate number of entries in this cache.
`CacheStats` `stats()` Returns a current snapshot of this cache's cumulative statistics.

Method Detail

### getIfPresent

    @Nullable
    V getIfPresent(Object key)

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

  Since:
    11.0

### get

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

  Returns the value associated with `key` in this cache, obtaining that value from `valueLoader` if necessary. No observable state associated with this cache is modified until loading completes. This method provides a simple substitute for the conventional "if cached, return; otherwise create, cache and return" pattern.

  Warning: as with `CacheLoader.load(K)`, `valueLoader` must not return `null`; it may either return a non-null value or throw an exception.

  Throws:
    `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

    ImmutableMap<K,V> getAllPresent(Iterable<?> 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

### put

    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

    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

### invalidate

    void invalidate(Object key)

  Discards any cached value for key `key`.

### invalidateAll

    void invalidateAll(Iterable<?> keys)

  Discards any cached values for keys `keys`.

  Since:
    11.0

### invalidateAll

    void invalidateAll()

  Discards all entries in the cache.

### size

    long size()

  Returns the approximate number of entries in this cache.

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

### asMap

    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.

### cleanUp

    void cleanUp()

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

Copyright © 2010-2012. All Rights Reserved.