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.collect.ImmutableMap;
022 import com.google.common.util.concurrent.ExecutionError;
023 import com.google.common.util.concurrent.UncheckedExecutionException;
024
025 import java.util.Map;
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(Object, Callable)} or {@link #put(Object, Object)}, and are stored in the cache until
035 * either evicted or manually invalidated.
036 *
037 * <p>Implementations of this interface are expected to be thread-safe, and can be safely accessed
038 * by multiple concurrent threads.
039 *
040 * <p>Note that while this class is still annotated as {@link Beta}, the API is frozen from a
041 * consumer's standpoint. In other words existing methods are all considered {@code non-Beta} and
042 * won't be changed without going through an 18 month deprecation cycle; however new methods may be
043 * added at any time.
044 *
045 * @author Charles Fry
046 * @since 10.0
047 */
048 @Beta
049 @GwtCompatible
050 public interface Cache<K, V> {
051
052 /**
053 * Returns the value associated with {@code key} in this cache, or {@code null} if there is no
054 * cached value for {@code key}.
055 *
056 * @since 11.0
057 */
058 @Nullable
059 V getIfPresent(Object key);
060
061 /**
062 * Returns the value associated with {@code key} in this cache, obtaining that value from
063 * {@code valueLoader} if necessary. No observable state associated with this cache is modified
064 * until loading completes. This method provides a simple substitute for the conventional
065 * "if cached, return; otherwise create, cache and return" pattern.
066 *
067 * <p><b>Warning:</b> as with {@link CacheLoader#load}, {@code valueLoader} <b>must not</b> return
068 * {@code null}; it may either return a non-null value or throw an exception.
069 *
070 * @throws ExecutionException if a checked exception was thrown while loading the value
071 * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the
072 * value
073 * @throws ExecutionError if an error was thrown while loading the value
074 *
075 * @since 11.0
076 */
077 V get(K key, Callable<? extends V> valueLoader) throws ExecutionException;
078
079 /**
080 * Returns a map of the values associated with {@code keys} in this cache. The returned map will
081 * only contain entries which are already present in the cache.
082 *
083 * @since 11.0
084 */
085 ImmutableMap<K, V> getAllPresent(Iterable<?> keys);
086
087 /**
088 * Associates {@code value} with {@code key} in this cache. If the cache previously contained a
089 * value associated with {@code key}, the old value is replaced by {@code value}.
090 *
091 * <p>Prefer {@link #get(Object, Callable)} when using the conventional "if cached, return;
092 * otherwise create, cache and return" pattern.
093 *
094 * @since 11.0
095 */
096 void put(K key, V value);
097
098 /**
099 * Copies all of the mappings from the specified map to the cache. The effect of this call is
100 * equivalent to that of calling {@code put(k, v)} on this map once for each mapping from key
101 * {@code k} to value {@code v} in the specified map. The behavior of this operation is undefined
102 * if the specified map is modified while the operation is in progress.
103 *
104 * @since 12.0
105 */
106 void putAll(Map<? extends K,? extends V> m);
107
108 /**
109 * Discards any cached value for key {@code key}.
110 */
111 void invalidate(Object key);
112
113 /**
114 * Discards any cached values for keys {@code keys}.
115 *
116 * @since 11.0
117 */
118 void invalidateAll(Iterable<?> keys);
119
120 /**
121 * Discards all entries in the cache.
122 */
123 void invalidateAll();
124
125 /**
126 * Returns the approximate number of entries in this cache.
127 */
128 long size();
129
130 /**
131 * Returns a current snapshot of this cache's cumulative statistics. All stats are initialized
132 * to zero, and are monotonically increasing over the lifetime of the cache.
133 */
134 CacheStats stats();
135
136 /**
137 * Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to
138 * the map directly affect the cache.
139 */
140 ConcurrentMap<K, V> asMap();
141
142 /**
143 * Performs any pending maintenance operations needed by the cache. Exactly which activities are
144 * performed -- if any -- is implementation-dependent.
145 */
146 void cleanUp();
147 }