1 /* 2 * Copyright (C) 2011 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.cache; 18 19 import com.google.common.annotations.Beta; 20 import com.google.common.annotations.GwtCompatible; 21 import com.google.common.base.Function; 22 import com.google.common.collect.ImmutableMap; 23 import com.google.common.util.concurrent.ExecutionError; 24 import com.google.common.util.concurrent.UncheckedExecutionException; 25 26 import java.util.concurrent.Callable; 27 import java.util.concurrent.ConcurrentMap; 28 import java.util.concurrent.ExecutionException; 29 30 import javax.annotation.Nullable; 31 32 /** 33 * A semi-persistent mapping from keys to values. Cache entries are manually added using 34 * {@link #get(K, Callable)} or {@link #put(K, V)}, and are stored in the cache until either 35 * evicted or manually invalidated. 36 * 37 * <p><b>Note:</b> in release 12.0, all methods moved from {@code Cache} to {@link LoadingCache} 38 * will be deleted from {@code Cache}. As part of this transition {@code Cache} will no longer 39 * extend {@link Function}. 40 * 41 * <p>Implementations of this interface are expected to be thread-safe, and can be safely accessed 42 * by multiple concurrent threads. 43 * 44 * <p>All methods other than {@link #getIfPresent} are optional. 45 * 46 * @author Charles Fry 47 * @since 10.0 48 */ 49 @Beta 50 @GwtCompatible 51 public interface Cache<K, V> extends Function<K, V> { 52 53 /** 54 * Returns the value associated with {@code key} in this cache, or {@code null} if there is no 55 * cached value for {@code key}. 56 * 57 * @since 11.0 58 */ 59 @Nullable 60 V getIfPresent(K key); 61 62 /** 63 * Returns the value associated with {@code key} in this cache, obtaining that value from 64 * {@code valueLoader} if necessary. No observable state associated with this cache is modified 65 * until loading completes. This method provides a simple substitute for the conventional 66 * "if cached, return; otherwise create, cache and return" pattern. 67 * 68 * <p><b>Warning:</b> as with {@link CacheLoader#load}, {@code valueLoader} <b>must not</b> return 69 * {@code null}; it may either return a non-null value or throw an exception. 70 * 71 * @throws ExecutionException if a checked exception was thrown while loading the value 72 * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the 73 * value 74 * @throws ExecutionError if an error was thrown while loading the value 75 * 76 * @since 11.0 77 */ 78 V get(K key, Callable<? extends V> valueLoader) throws ExecutionException; 79 80 /** 81 * Returns a map of the values associated with {@code keys} in this cache. The returned map will 82 * only contain entries which are already present in the cache. 83 * 84 * @since 11.0 85 */ 86 ImmutableMap<K, V> getAllPresent(Iterable<? extends K> keys); 87 88 /** 89 * Associates {@code value} with {@code key} in this cache. If the cache previously contained a 90 * value associated with {@code key}, the old value is replaced by {@code value}. 91 * 92 * <p>Prefer {@link #get(Object, Callable)} when using the conventional "if cached, return; 93 * otherwise create, cache and return" pattern. 94 * 95 * @since 11.0 96 */ 97 void put(K key, V value); 98 99 /** 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 } 190
