11d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert/* 21d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Copyright (C) 2011 The Guava Authors 31d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 41d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Licensed under the Apache License, Version 2.0 (the "License"); 51d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * you may not use this file except in compliance with the License. 61d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * You may obtain a copy of the License at 71d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 81d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * http://www.apache.org/licenses/LICENSE-2.0 91d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 101d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Unless required by applicable law or agreed to in writing, software 111d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * distributed under the License is distributed on an "AS IS" BASIS, 121d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 131d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * See the License for the specific language governing permissions and 141d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * limitations under the License. 151d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 161d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 171d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertpackage com.google.common.cache; 181d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 191d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport com.google.common.annotations.Beta; 201d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport com.google.common.annotations.GwtCompatible; 211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport com.google.common.base.Function; 221d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport com.google.common.collect.ImmutableMap; 231d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport com.google.common.util.concurrent.ExecutionError; 241d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport com.google.common.util.concurrent.UncheckedExecutionException; 251d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 261d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.concurrent.Callable; 271d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.concurrent.ConcurrentMap; 281d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.concurrent.ExecutionException; 291d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 301d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport javax.annotation.Nullable; 311d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 321d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert/** 331d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * A semi-persistent mapping from keys to values. Cache entries are manually added using 341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link #get(K, Callable)} or {@link #put(K, V)}, and are stored in the cache until either 351d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * evicted or manually invalidated. 361d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 371d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p><b>Note:</b> in release 12.0, all methods moved from {@code Cache} to {@link LoadingCache} 381d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * will be deleted from {@code Cache}. As part of this transition {@code Cache} will no longer 391d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * extend {@link Function}. 401d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>Implementations of this interface are expected to be thread-safe, and can be safely accessed 421d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * by multiple concurrent threads. 431d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 441d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>All methods other than {@link #getIfPresent} are optional. 451d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 461d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @author Charles Fry 471d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 10.0 481d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 491d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert@Beta 501d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert@GwtCompatible 511d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertpublic interface Cache<K, V> extends Function<K, V> { 521d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 531d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 541d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns the value associated with {@code key} in this cache, or {@code null} if there is no 551d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * cached value for {@code key}. 561d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 571d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 11.0 581d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 591d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert @Nullable 601d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert V getIfPresent(K key); 611d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 621d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 631d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns the value associated with {@code key} in this cache, obtaining that value from 641d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code valueLoader} if necessary. No observable state associated with this cache is modified 651d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * until loading completes. This method provides a simple substitute for the conventional 661d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * "if cached, return; otherwise create, cache and return" pattern. 671d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 681d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p><b>Warning:</b> as with {@link CacheLoader#load}, {@code valueLoader} <b>must not</b> return 691d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code null}; it may either return a non-null value or throw an exception. 701d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 711d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws ExecutionException if a checked exception was thrown while loading the value 721d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the 731d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * value 741d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws ExecutionError if an error was thrown while loading the value 751d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 761d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 11.0 771d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 781d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert V get(K key, Callable<? extends V> valueLoader) throws ExecutionException; 791d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 801d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 811d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns a map of the values associated with {@code keys} in this cache. The returned map will 821d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * only contain entries which are already present in the cache. 831d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 841d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 11.0 851d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 861d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert ImmutableMap<K, V> getAllPresent(Iterable<? extends K> keys); 871d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 881d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 891d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Associates {@code value} with {@code key} in this cache. If the cache previously contained a 901d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * value associated with {@code key}, the old value is replaced by {@code value}. 911d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 921d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>Prefer {@link #get(Object, Callable)} when using the conventional "if cached, return; 931d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * otherwise create, cache and return" pattern. 941d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 951d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 11.0 961d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 971d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert void put(K key, V value); 981d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 991d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 1001d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Discards any cached value for key {@code key}. 1011d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1021d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert void invalidate(Object key); 1031d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 1041d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 1051d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Discards any cached values for keys {@code keys}. 1061d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 1071d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 11.0 1081d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1091d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert void invalidateAll(Iterable<?> keys); 1101d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 1111d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 1121d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Discards all entries in the cache. 1131d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1141d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert void invalidateAll(); 1151d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 1161d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 1171d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns the approximate number of entries in this cache. 1181d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1191d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert long size(); 1201d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 1211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 1221d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns a current snapshot of this cache's cumulative statistics. All stats are initialized 1231d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * to zero, and are monotonically increasing over the lifetime of the cache. 1241d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1251d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert CacheStats stats(); 1261d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 1271d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 1281d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to 1291d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * the map directly affect the cache. 1301d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1311d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert ConcurrentMap<K, V> asMap(); 1321d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 1331d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 1341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Performs any pending maintenance operations needed by the cache. Exactly which activities are 1351d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * performed -- if any -- is implementation-dependent. 1361d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1371d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert void cleanUp(); 1381d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 1391d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 1401d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns the value associated with {@code key} in this cache, first loading that value if 1411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * necessary. No observable state associated with this cache is modified until loading completes. 1421d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 1431d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws ExecutionException if a checked exception was thrown while loading the value 1441d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the 1451d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * value 1461d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws ExecutionError if an error was thrown while loading the value 1471d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @deprecated This method has been split out into the {@link LoadingCache} interface, and will be 1481d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * removed from {@code Cache} in Guava release 12.0. Note that 1491d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link CacheBuilder#build(CacheLoader)} now returns a {@code LoadingCache}, so this deprecation 1501d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * (migration) can be dealt with by simply changing the type of references to the results of 1511d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link CacheBuilder#build(CacheLoader)}. 1521d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1531d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert @Deprecated V get(K key) throws ExecutionException; 1541d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 1551d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 1561d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns the value associated with {@code key} in this cache, first loading that value if 1571d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * necessary. No observable state associated with this cache is modified until computation 1581d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * completes. Unlike {@link #get}, this method does not throw a checked exception, and thus should 1591d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * only be used in situations where checked exceptions are not thrown by the cache loader. 1601d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 1611d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p><b>Warning:</b> this method silently converts checked exceptions to unchecked exceptions, 1621d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * and should not be used with cache loaders which throw checked exceptions. 1631d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 1641d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws UncheckedExecutionException if an exception was thrown while loading the value, 1651d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * regardless of whether the exception was checked or unchecked 1661d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws ExecutionError if an error was thrown while loading the value 1671d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @deprecated This method has been split out into the {@link LoadingCache} interface, and will be 1681d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * removed from {@code Cache} in Guava release 12.0. Note that 1691d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link CacheBuilder#build(CacheLoader)} now returns a {@code LoadingCache}, so this deprecation 1701d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * (migration) can be dealt with by simply changing the type of references to the results of 1711d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link CacheBuilder#build(CacheLoader)}. 1721d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1731d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert @Deprecated V getUnchecked(K key); 1741d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 1751d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 1761d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Discouraged. Provided to satisfy the {@code Function} interface; use {@link #get} or 1771d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link #getUnchecked} instead. 1781d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 1791d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws UncheckedExecutionException if an exception was thrown while loading the value, 1801d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * regardless of whether the exception was checked or unchecked 1811d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws ExecutionError if an error was thrown while loading the value 1821d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @deprecated This method has been split out into the {@link LoadingCache} interface, and will be 1831d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * removed from {@code Cache} in Guava release 12.0. Note that 1841d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link CacheBuilder#build(CacheLoader)} now returns a {@code LoadingCache}, so this deprecation 1851d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * (migration) can be dealt with by simply changing the type of references to the results of 1861d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link CacheBuilder#build(CacheLoader)}. 1871d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 1881d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert @Deprecated V apply(K key); 1891d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert} 190