001/*
002 * Copyright (C) 2011 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.cache;
016
017import com.google.common.annotations.GwtCompatible;
018import com.google.common.collect.ImmutableMap;
019import com.google.common.util.concurrent.ExecutionError;
020import com.google.common.util.concurrent.UncheckedExecutionException;
021import com.google.errorprone.annotations.CanIgnoreReturnValue;
022import com.google.errorprone.annotations.CompatibleWith;
023import com.google.errorprone.annotations.DoNotMock;
024import java.util.Map;
025import java.util.concurrent.Callable;
026import java.util.concurrent.ConcurrentMap;
027import java.util.concurrent.ExecutionException;
028import javax.annotation.CheckForNull;
029
030/**
031 * A semi-persistent mapping from keys to values. Cache entries are manually added using {@link
032 * #get(Object, Callable)} or {@link #put(Object, Object)}, and are stored in the cache until either
033 * evicted or manually invalidated. The common way to build instances is using {@link CacheBuilder}.
034 *
035 * <p>Implementations of this interface are expected to be thread-safe, and can be safely accessed
036 * by multiple concurrent threads.
037 *
038 * @param <K> the type of the cache's keys, which are not permitted to be null
039 * @param <V> the type of the cache's values, which are not permitted to be null
040 * @author Charles Fry
041 * @since 10.0
042 */
043@DoNotMock("Use CacheBuilder.newBuilder().build()")
044@GwtCompatible
045@ElementTypesAreNonnullByDefault
046public interface Cache<K, V> {
047
048  /**
049   * Returns the value associated with {@code key} in this cache, or {@code null} if there is no
050   * cached value for {@code key}.
051   *
052   * @since 11.0
053   */
054  @CheckForNull
055  @CanIgnoreReturnValue // TODO(b/27479612): consider removing this?
056  V getIfPresent(@CompatibleWith("K") Object key);
057
058  /**
059   * Returns the value associated with {@code key} in this cache, obtaining that value from {@code
060   * loader} if necessary. The method improves upon the conventional "if cached, return; otherwise
061   * create, cache and return" pattern. For further improvements, use {@link LoadingCache} and its
062   * {@link LoadingCache#get(Object) get(K)} method instead of this one.
063   *
064   * <p>Among the improvements that this method and {@code LoadingCache.get(K)} both provide are:
065   *
066   * <ul>
067   *   <li>{@linkplain LoadingCache#get(Object) awaiting the result of a pending load} rather than
068   *       starting a redundant one
069   *   <li>eliminating the error-prone caching boilerplate
070   *   <li>tracking load {@linkplain #stats statistics}
071   * </ul>
072   *
073   * <p>Among the further improvements that {@code LoadingCache} can provide but this method cannot:
074   *
075   * <ul>
076   *   <li>consolidation of the loader logic to {@linkplain CacheBuilder#build(CacheLoader) a single
077   *       authoritative location}
078   *   <li>{@linkplain LoadingCache#refresh refreshing of entries}, including {@linkplain
079   *       CacheBuilder#refreshAfterWrite automated refreshing}
080   *   <li>{@linkplain LoadingCache#getAll bulk loading requests}, including {@linkplain
081   *       CacheLoader#loadAll bulk loading implementations}
082   * </ul>
083   *
084   * <p><b>Warning:</b> For any given key, every {@code loader} used with it should compute the same
085   * value. Otherwise, a call that passes one {@code loader} may return the result of another call
086   * with a differently behaving {@code loader}. For example, a call that requests a short timeout
087   * for an RPC may wait for a similar call that requests a long timeout, or a call by an
088   * unprivileged user may return a resource accessible only to a privileged user making a similar
089   * call. To prevent this problem, create a key object that includes all values that affect the
090   * result of the query. Or use {@code LoadingCache.get(K)}, which lacks the ability to refer to
091   * state other than that in the key.
092   *
093   * <p><b>Warning:</b> as with {@link CacheLoader#load}, {@code loader} <b>must not</b> return
094   * {@code null}; it may either return a non-null value or throw an exception.
095   *
096   * <p>No observable state associated with this cache is modified until loading completes.
097   *
098   * @throws ExecutionException if a checked exception was thrown while loading the value
099   * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the
100   *     value
101   * @throws ExecutionError if an error was thrown while loading the value
102   * @since 11.0
103   */
104  @CanIgnoreReturnValue // TODO(b/27479612): consider removing this
105  V get(K key, Callable<? extends V> loader) throws ExecutionException;
106
107  /**
108   * Returns a map of the values associated with {@code keys} in this cache. The returned map will
109   * only contain entries which are already present in the cache.
110   *
111   * @since 11.0
112   */
113  /*
114   * <? extends Object> is mostly the same as <?> to plain Java. But to nullness checkers, they
115   * differ: <? extends Object> means "non-null types," while <?> means "all types."
116   */
117  ImmutableMap<K, V> getAllPresent(Iterable<? extends Object> keys);
118
119  /**
120   * Associates {@code value} with {@code key} in this cache. If the cache previously contained a
121   * value associated with {@code key}, the old value is replaced by {@code value}.
122   *
123   * <p>Prefer {@link #get(Object, Callable)} when using the conventional "if cached, return;
124   * otherwise create, cache and return" pattern.
125   *
126   * @since 11.0
127   */
128  void put(K key, V value);
129
130  /**
131   * Copies all of the mappings from the specified map to the cache. The effect of this call is
132   * equivalent to that of calling {@code put(k, v)} on this map once for each mapping from key
133   * {@code k} to value {@code v} in the specified map. The behavior of this operation is undefined
134   * if the specified map is modified while the operation is in progress.
135   *
136   * @since 12.0
137   */
138  void putAll(Map<? extends K, ? extends V> m);
139
140  /** Discards any cached value for key {@code key}. */
141  void invalidate(@CompatibleWith("K") Object key);
142
143  /**
144   * Discards any cached values for keys {@code keys}.
145   *
146   * @since 11.0
147   */
148  // For discussion of <? extends Object>, see getAllPresent.
149  void invalidateAll(Iterable<? extends Object> keys);
150
151  /** Discards all entries in the cache. */
152  void invalidateAll();
153
154  /** Returns the approximate number of entries in this cache. */
155  long size();
156
157  /**
158   * Returns a current snapshot of this cache's cumulative statistics, or a set of default values if
159   * the cache is not recording statistics. All statistics begin at zero and never decrease over the
160   * lifetime of the cache.
161   *
162   * <p><b>Warning:</b> this cache may not be recording statistical data. For example, a cache
163   * created using {@link CacheBuilder} only does so if the {@link CacheBuilder#recordStats} method
164   * was called. If statistics are not being recorded, a {@code CacheStats} instance with zero for
165   * all values is returned.
166   *
167   */
168  CacheStats stats();
169
170  /**
171   * Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to
172   * the map directly affect the cache.
173   *
174   * <p>Iterators from the returned map are at least <i>weakly consistent</i>: they are safe for
175   * concurrent use, but if the cache is modified (including by eviction) after the iterator is
176   * created, it is undefined which of the changes (if any) will be reflected in that iterator.
177   *
178   * <p><b>Warning to users of Java 8+:</b> do not call any of the new <i>default methods</i> that
179   * have been newly added to {@link ConcurrentMap}! These are marked with "Since: 1.8" in the
180   * {@code ConcurrentMap} documentation. They will not function correctly and it is impossible for
181   * Guava to fix them until Guava is ready to <i>require</i> Java 8 for all users.
182   */
183  ConcurrentMap<K, V> asMap();
184
185  /**
186   * Performs any pending maintenance operations needed by the cache. Exactly which activities are
187   * performed -- if any -- is implementation-dependent.
188   */
189  void cleanUp();
190}