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

All Superinterfaces:
  Cache<K,V>, Function<K,V>

All Known Implementing Classes:
  AbstractLoadingCache, ForwardingLoadingCache, ForwardingLoadingCache.SimpleForwardingLoadingCache

    @Beta
    @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.

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 invoking `getUnchecked(K)`.

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:
  11.0
Author:
  Charles Fry

Method Summary
`V` `apply(K key)` Discouraged.
`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 with `key` in this cache, first loading that value if necessary.
`ImmutableMap<K,V>` `getAll(Iterable<? extends K> keys)` Returns a map of the values associated with `keys`, creating or retrieving those values if necessary.
`V` `getUnchecked(K key)` Returns the value associated with `key` in this cache, first loading that value if necessary.
`void` `refresh(K key)` Loads a new value for key `key`, possibly asynchronously.

Methods inherited from interface com.google.common.cache.Cache
`cleanUp, get, getAllPresent, getIfPresent, invalidate, invalidateAll, invalidateAll, put, putAll, size, stats`

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

Method Detail

### get

    V get(K key)
          throws ExecutionException

  Returns the value associated with `key` 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)` or `getUnchecked(K)` is currently loading the value for `key`, 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 call `CacheLoader.load(K)` to load new values into the cache. Newly loaded values are added to the cache using `Cache.asMap().putIfAbsent` after loading has completed; if another value was associated with `key` 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:
    `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

### getUnchecked

    V getUnchecked(K key)

  Returns the value associated with `key` in this cache, first loading that value if necessary. No observable state associated with this cache is modified until loading 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.

  If another call to `get(K)` or `getUnchecked(K)` is currently loading the value for `key`, 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 call `CacheLoader.load(K)` to load new values into the cache. Newly loaded values are added to the cache using `Cache.asMap().putIfAbsent` after loading has completed; if another value was associated with `key` 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, regardless of whether the exception was checked or unchecked
    `ExecutionError` - if an error was thrown while loading the value

### getAll

    ImmutableMap<K,V> getAll(Iterable<? extends K> keys)
                             throws ExecutionException

  Returns a map of the values associated with `keys`, 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 to `CacheLoader.loadAll(java.lang.Iterable<? extends K>)` for all keys which are not already present in the cache. All entries returned by `CacheLoader.loadAll(java.lang.Iterable<? extends K>)` will be stored in the cache, over-writing any previously cached values. This method will throw an exception if `CacheLoader.loadAll(java.lang.Iterable<? extends K>)` returns `null`, 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 by `Object.equals(java.lang.Object)`, will be ignored.

  Throws:
    `ExecutionException` - if a checked exception was thrown while loading the values
    `UncheckedExecutionException` - if an unchecked exception was thrown while loading the values
    `ExecutionError` - if an error was thrown while loading the values
  Since:
    11.0

### apply

    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 value, regardless of whether the exception was checked or unchecked
    `ExecutionError` - if an error was thrown while loading the value

### refresh

    void refresh(K key)

  Loads a new value for key `key`, possibly 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 `Logger`) and swallowed.

  Caches loaded by a `CacheLoader` will call `CacheLoader.reload(K, V)` if the cache currently contains a value for `key`, and `CacheLoader.load(K)` otherwise. Loading is asynchronous only if `CacheLoader.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

    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.

  Note that although the view is modifiable, no method on the returned map will ever cause entries to be automatically loaded.

  Specified by:
    `asMap` in interface `Cache<K,V>`

Copyright © 2010-2012. All Rights Reserved.