View Javadoc
1   /*
2    * Copyright (C) 2011 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5    * in compliance with the License. You may obtain a copy of the License at
6    *
7    * http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software distributed under the License
10   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11   * or implied. See the License for the specific language governing permissions and limitations under
12   * the License.
13   */
14  
15  package com.google.common.cache;
16  
17  import com.google.common.annotations.GwtCompatible;
18  import com.google.common.base.Function;
19  import com.google.common.collect.ImmutableMap;
20  import com.google.common.util.concurrent.ExecutionError;
21  import com.google.common.util.concurrent.UncheckedExecutionException;
22  import java.util.concurrent.ConcurrentMap;
23  import java.util.concurrent.ExecutionException;
24  
25  /**
26   * A semi-persistent mapping from keys to values. Values are automatically loaded by the cache, and
27   * are stored in the cache until either evicted or manually invalidated. The common way to build
28   * instances is using {@link CacheBuilder}.
29   *
30   * <p>Implementations of this interface are expected to be thread-safe, and can be safely accessed
31   * by multiple concurrent threads.
32   *
33   * <p>When evaluated as a {@link Function}, a cache yields the same result as invoking
34   * {@link #getUnchecked}.
35   *
36   * @author Charles Fry
37   * @since 11.0
38   */
39  @GwtCompatible
40  public interface LoadingCache<K, V> extends Cache<K, V>, Function<K, V> {
41  
42    /**
43     * Returns the value associated with {@code key} in this cache, first loading that value if
44     * necessary. No observable state associated with this cache is modified until loading completes.
45     *
46     * <p>If another call to {@link #get} or {@link #getUnchecked} is currently loading the value for
47     * {@code key}, simply waits for that thread to finish and returns its loaded value. Note that
48     * multiple threads can concurrently load values for distinct keys.
49     *
50     * <p>Caches loaded by a {@link CacheLoader} will call {@link CacheLoader#load} to load new values
51     * into the cache. Newly loaded values are added to the cache using
52     * {@code Cache.asMap().putIfAbsent} after loading has completed; if another value was associated
53     * with {@code key} while the new value was loading then a removal notification will be sent for
54     * the new value.
55     *
56     * <p>If the cache loader associated with this cache is known not to throw checked exceptions,
57     * then prefer {@link #getUnchecked} over this method.
58     *
59     * @throws ExecutionException if a checked exception was thrown while loading the value. ({@code
60     *     ExecutionException} is thrown
61     *     <a href="https://github.com/google/guava/wiki/CachesExplained#interruption">even if
62     *     computation was interrupted by an {@code InterruptedException}</a>.)
63     * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the
64     *     value
65     * @throws ExecutionError if an error was thrown while loading the value
66     */
67    V get(K key) throws ExecutionException;
68  
69    /**
70     * Returns the value associated with {@code key} in this cache, first loading that value if
71     * necessary. No observable state associated with this cache is modified until loading completes.
72     * Unlike {@link #get}, this method does not throw a checked exception, and thus should only be
73     * used in situations where checked exceptions are not thrown by the cache loader.
74     *
75     * <p>If another call to {@link #get} or {@link #getUnchecked} is currently loading the value for
76     * {@code key}, simply waits for that thread to finish and returns its loaded value. Note that
77     * multiple threads can concurrently load values for distinct keys.
78     *
79     * <p>Caches loaded by a {@link CacheLoader} will call {@link CacheLoader#load} to load new values
80     * into the cache. Newly loaded values are added to the cache using
81     * {@code Cache.asMap().putIfAbsent} after loading has completed; if another value was associated
82     * with {@code key} while the new value was loading then a removal notification will be sent for
83     * the new value.
84     *
85     * <p><b>Warning:</b> this method silently converts checked exceptions to unchecked exceptions,
86     * and should not be used with cache loaders which throw checked exceptions. In such cases use
87     * {@link #get} instead.
88     *
89     * @throws UncheckedExecutionException if an exception was thrown while loading the value. (As
90     *     explained in the last paragraph above, this should be an unchecked exception only.)
91     * @throws ExecutionError if an error was thrown while loading the value
92     */
93    V getUnchecked(K key);
94  
95    /**
96     * Returns a map of the values associated with {@code keys}, creating or retrieving those values
97     * if necessary. The returned map contains entries that were already cached, combined with newly
98     * loaded entries; it will never contain null keys or values.
99     *
100    * <p>Caches loaded by a {@link CacheLoader} will issue a single request to
101    * {@link CacheLoader#loadAll} for all keys which are not already present in the cache. All
102    * entries returned by {@link CacheLoader#loadAll} will be stored in the cache, over-writing any
103    * previously cached values. This method will throw an exception if {@link CacheLoader#loadAll}
104    * returns {@code null}, returns a map containing null keys or values, or fails to return an entry
105    * for each requested key.
106    *
107    * <p>Note that duplicate elements in {@code keys}, as determined by {@link Object#equals}, will
108    * be ignored.
109    *
110    * @throws ExecutionException if a checked exception was thrown while loading the value. ({@code
111    *     ExecutionException} is thrown
112    *     <a href="https://github.com/google/guava/wiki/CachesExplained#interruption">even if
113    *     computation was interrupted by an {@code InterruptedException}</a>.)
114    * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the
115    *     values
116    * @throws ExecutionError if an error was thrown while loading the values
117    * @since 11.0
118    */
119   ImmutableMap<K, V> getAll(Iterable<? extends K> keys) throws ExecutionException;
120 
121   /**
122    * @deprecated Provided to satisfy the {@code Function} interface; use {@link #get} or
123    *     {@link #getUnchecked} instead.
124    * @throws UncheckedExecutionException if an exception was thrown while loading the value. (As
125    *     described in the documentation for {@link #getUnchecked}, {@code LoadingCache} should be
126    *     used as a {@code Function} only with cache loaders that throw only unchecked exceptions.)
127    */
128   @Deprecated
129   @Override
130   V apply(K key);
131 
132   /**
133    * Loads a new value for key {@code key}, possibly asynchronously. While the new value is loading
134    * the previous value (if any) will continue to be returned by {@code get(key)} unless it is
135    * evicted. If the new value is loaded successfully it will replace the previous value in the
136    * cache; if an exception is thrown while refreshing the previous value will remain, <i>and the
137    * exception will be logged (using {@link java.util.logging.Logger}) and swallowed</i>.
138    *
139    * <p>Caches loaded by a {@link CacheLoader} will call {@link CacheLoader#reload} if the cache
140    * currently contains a value for {@code key}, and {@link CacheLoader#load} otherwise. Loading is
141    * asynchronous only if {@link CacheLoader#reload} was overridden with an asynchronous
142    * implementation.
143    *
144    * <p>Returns without doing anything if another thread is currently loading the value for
145    * {@code key}. If the cache loader associated with this cache performs refresh asynchronously
146    * then this method may return before refresh completes.
147    *
148    * @since 11.0
149    */
150   void refresh(K key);
151 
152   /**
153    * {@inheritDoc}
154    *
155    * <p><b>Note that although the view <i>is</i> modifiable, no method on the returned map will ever
156    * cause entries to be automatically loaded.</b>
157    */
158   @Override
159   ConcurrentMap<K, V> asMap();
160 }