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.collect.ImmutableMap; 22 import com.google.common.util.concurrent.ExecutionError; 23 import com.google.common.util.concurrent.UncheckedExecutionException; 24 25 import java.util.Map; 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(Object, Callable)} or {@link #put(Object, Object)}, and are stored in the cache until 35 * either evicted or manually invalidated. 36 * 37 * <p>Implementations of this interface are expected to be thread-safe, and can be safely accessed 38 * by multiple concurrent threads. 39 * 40 * <p>Note that while this class is still annotated as {@link Beta}, the API is frozen from a 41 * consumer's standpoint. In other words existing methods are all considered {@code non-Beta} and 42 * won't be changed without going through an 18 month deprecation cycle; however new methods may be 43 * added at any time. 44 * 45 * @author Charles Fry 46 * @since 10.0 47 */ 48 @Beta 49 @GwtCompatible 50 public interface Cache<K, V> { 51 52 /** 53 * Returns the value associated with {@code key} in this cache, or {@code null} if there is no 54 * cached value for {@code key}. 55 * 56 * @since 11.0 57 */ 58 @Nullable 59 V getIfPresent(Object key); 60 61 /** 62 * Returns the value associated with {@code key} in this cache, obtaining that value from 63 * {@code valueLoader} if necessary. No observable state associated with this cache is modified 64 * until loading completes. This method provides a simple substitute for the conventional 65 * "if cached, return; otherwise create, cache and return" pattern. 66 * 67 * <p><b>Warning:</b> as with {@link CacheLoader#load}, {@code valueLoader} <b>must not</b> return 68 * {@code null}; it may either return a non-null value or throw an exception. 69 * 70 * @throws ExecutionException if a checked exception was thrown while loading the value 71 * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the 72 * value 73 * @throws ExecutionError if an error was thrown while loading the value 74 * 75 * @since 11.0 76 */ 77 V get(K key, Callable<? extends V> valueLoader) throws ExecutionException; 78 79 /** 80 * Returns a map of the values associated with {@code keys} in this cache. The returned map will 81 * only contain entries which are already present in the cache. 82 * 83 * @since 11.0 84 */ 85 ImmutableMap<K, V> getAllPresent(Iterable<?> keys); 86 87 /** 88 * Associates {@code value} with {@code key} in this cache. If the cache previously contained a 89 * value associated with {@code key}, the old value is replaced by {@code value}. 90 * 91 * <p>Prefer {@link #get(Object, Callable)} when using the conventional "if cached, return; 92 * otherwise create, cache and return" pattern. 93 * 94 * @since 11.0 95 */ 96 void put(K key, V value); 97 98 /** 99 * 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 */ 135 CacheStats stats(); 136 137 /** 138 * Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to 139 * the map directly affect the cache. 140 * 141 * <p>Iterators from the returned map are at least <i>weakly consistent</i>: they are safe for 142 * concurrent use, but if the cache is modified (including by eviction) after the iterator is 143 * created, it is undefined which of the changes (if any) will be reflected in that iterator. 144 */ 145 ConcurrentMap<K, V> asMap(); 146 147 /** 148 * Performs any pending maintenance operations needed by the cache. Exactly which activities are 149 * performed -- if any -- is implementation-dependent. 150 */ 151 void cleanUp(); 152 } 153
