Package com.google.common.cache

Interface LoadingCache<K,​V>

  • Type Parameters:
    K - the type of the cache's keys, which are not permitted to be null
    V - the type of the cache's values, which are not permitted to be null
    All Superinterfaces:
    Cache<K,​V>, Function<K,​V>
    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 using CacheBuilder.

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

    Since:
    11.0
    Author:
    Charles Fry

    • Method Detail

      • get

        @CanIgnoreReturnValue
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. ( ExecutionException is thrown even if computation was interrupted by an InterruptedException.)
        UncheckedExecutionException - if an unchecked exception was thrown while loading the value
        ExecutionError - if an error was thrown while loading the value

      • getUnchecked

        @CanIgnoreReturnValue
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. (As explained in the last paragraph above, this should be an unchecked exception only.)
        ExecutionError - if an error was thrown while loading the value

      • apply

        @Deprecated
V apply​(K key)
        Deprecated.
        Provided to satisfy the Function interface; use get(K) or getUnchecked(K) instead.
        Description copied from interface: Function
        Returns the result of applying this function to input. This method is generally expected, but not absolutely required, to have the following properties:
        • Its execution does not cause any observable side effects.
        • The computation is consistent with equals; that is, Objects.equal(a, b) implies that Objects.equal(function.apply(a), function.apply(b)).
        Specified by:
        apply in interface Function<K,​V>
        Throws:
        UncheckedExecutionException - if an exception was thrown while loading the value. (As described in the documentation for getUnchecked(K), LoadingCache should be used as a Function only with cache loaders that throw only unchecked exceptions.)

      • refresh

        void refresh​(K key)
        Loads a new value for 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.

        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.

        Warning to users of Java 8+: do not call any of the new default methods that have been newly added to ConcurrentMap! These are marked with "Since: 1.8" in the ConcurrentMap documentation. They will not function correctly and it is impossible for Guava to fix them until Guava is ready to require Java 8 for all users.

        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>