001 /*
002 * Copyright (C) 2011 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package com.google.common.cache;
018
019 import com.google.common.annotations.Beta;
020 import com.google.common.annotations.GwtCompatible;
021 import com.google.common.base.Function;
022 import com.google.common.collect.ImmutableMap;
023 import com.google.common.util.concurrent.ExecutionError;
024 import com.google.common.util.concurrent.UncheckedExecutionException;
025
026 import java.util.concurrent.Callable;
027 import java.util.concurrent.ConcurrentMap;
028 import java.util.concurrent.ExecutionException;
029
030 import javax.annotation.Nullable;
031
032 /**
033 * A semi-persistent mapping from keys to values. Cache entries are manually added using
034 * {@link #get(K, Callable)} or {@link #put(K, V)}, and are stored in the cache until either
035 * evicted or manually invalidated.
036 *
037 * <p><b>Note:</b> in release 12.0, all methods moved from {@code Cache} to {@link LoadingCache}
038 * will be deleted from {@code Cache}. As part of this transition {@code Cache} will no longer
039 * extend {@link Function}.
040 *
041 * <p>Implementations of this interface are expected to be thread-safe, and can be safely accessed
042 * by multiple concurrent threads.
043 *
044 * <p>All methods other than {@link #getIfPresent} are optional.
045 *
046 * @author Charles Fry
047 * @since 10.0
048 */
049 @Beta
050 @GwtCompatible
051 public interface Cache<K, V> extends Function<K, V> {
052
053 /**
054 * Returns the value associated with {@code key} in this cache, or {@code null} if there is no
055 * cached value for {@code key}.
056 *
057 * @since 11.0
058 */
059 @Nullable
060 V getIfPresent(K key);
061
062 /**
063 * Returns the value associated with {@code key} in this cache, obtaining that value from
064 * {@code valueLoader} if necessary. No observable state associated with this cache is modified
065 * until loading completes. This method provides a simple substitute for the conventional
066 * "if cached, return; otherwise create, cache and return" pattern.
067 *
068 * <p><b>Warning:</b> as with {@link CacheLoader#load}, {@code valueLoader} <b>must not</b> return
069 * {@code null}; it may either return a non-null value or throw an exception.
070 *
071 * @throws ExecutionException if a checked exception was thrown while loading the value
072 * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the
073 * value
074 * @throws ExecutionError if an error was thrown while loading the value
075 *
076 * @since 11.0
077 */
078 V get(K key, Callable<? extends V> valueLoader) throws ExecutionException;
079
080 /**
081 * Returns a map of the values associated with {@code keys} in this cache. The returned map will
082 * only contain entries which are already present in the cache.
083 *
084 * @since 11.0
085 */
086 ImmutableMap<K, V> getAllPresent(Iterable<? extends K> keys);
087
088 /**
089 * Associates {@code value} with {@code key} in this cache. If the cache previously contained a
090 * value associated with {@code key}, the old value is replaced by {@code value}.
091 *
092 * <p>Prefer {@link #get(Object, Callable)} when using the conventional "if cached, return;
093 * otherwise create, cache and return" pattern.
094 *
095 * @since 11.0
096 */
097 void put(K key, V value);
098
099 /**
100 * Discards any cached value for key {@code key}.
101 */
102 void invalidate(Object key);
103
104 /**
105 * Discards any cached values for keys {@code keys}.
106 *
107 * @since 11.0
108 */
109 void invalidateAll(Iterable<?> keys);
110
111 /**
112 * Discards all entries in the cache.
113 */
114 void invalidateAll();
115
116 /**
117 * Returns the approximate number of entries in this cache.
118 */
119 long size();
120
121 /**
122 * Returns a current snapshot of this cache's cumulative statistics. All stats are initialized
123 * to zero, and are monotonically increasing over the lifetime of the cache.
124 */
125 CacheStats stats();
126
127 /**
128 * Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to
129 * the map directly affect the cache.
130 */
131 ConcurrentMap<K, V> asMap();
132
133 /**
134 * Performs any pending maintenance operations needed by the cache. Exactly which activities are
135 * performed -- if any -- is implementation-dependent.
136 */
137 void cleanUp();
138
139 /**
140 * Returns the value associated with {@code key} in this cache, first loading that value if
141 * necessary. No observable state associated with this cache is modified until loading completes.
142 *
143 * @throws ExecutionException if a checked exception was thrown while loading the value
144 * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the
145 * value
146 * @throws ExecutionError if an error was thrown while loading the value
147 * @deprecated This method has been split out into the {@link LoadingCache} interface, and will be
148 * removed from {@code Cache} in Guava release 12.0. Note that
149 * {@link CacheBuilder#build(CacheLoader)} now returns a {@code LoadingCache}, so this deprecation
150 * (migration) can be dealt with by simply changing the type of references to the results of
151 * {@link CacheBuilder#build(CacheLoader)}.
152 */
153 @Deprecated V get(K key) throws ExecutionException;
154
155 /**
156 * Returns the value associated with {@code key} in this cache, first loading that value if
157 * necessary. No observable state associated with this cache is modified until computation
158 * completes. Unlike {@link #get}, this method does not throw a checked exception, and thus should
159 * only be used in situations where checked exceptions are not thrown by the cache loader.
160 *
161 * <p><b>Warning:</b> this method silently converts checked exceptions to unchecked exceptions,
162 * and should not be used with cache loaders which throw checked exceptions.
163 *
164 * @throws UncheckedExecutionException if an exception was thrown while loading the value,
165 * regardless of whether the exception was checked or unchecked
166 * @throws ExecutionError if an error was thrown while loading the value
167 * @deprecated This method has been split out into the {@link LoadingCache} interface, and will be
168 * removed from {@code Cache} in Guava release 12.0. Note that
169 * {@link CacheBuilder#build(CacheLoader)} now returns a {@code LoadingCache}, so this deprecation
170 * (migration) can be dealt with by simply changing the type of references to the results of
171 * {@link CacheBuilder#build(CacheLoader)}.
172 */
173 @Deprecated V getUnchecked(K key);
174
175 /**
176 * Discouraged. Provided to satisfy the {@code Function} interface; use {@link #get} or
177 * {@link #getUnchecked} instead.
178 *
179 * @throws UncheckedExecutionException if an exception was thrown while loading the value,
180 * regardless of whether the exception was checked or unchecked
181 * @throws ExecutionError if an error was thrown while loading the value
182 * @deprecated This method has been split out into the {@link LoadingCache} interface, and will be
183 * removed from {@code Cache} in Guava release 12.0. Note that
184 * {@link CacheBuilder#build(CacheLoader)} now returns a {@code LoadingCache}, so this deprecation
185 * (migration) can be dealt with by simply changing the type of references to the results of
186 * {@link CacheBuilder#build(CacheLoader)}.
187 */
188 @Deprecated V apply(K key);
189 }