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.base.Function;
021 import com.google.common.util.concurrent.ExecutionError;
022 import com.google.common.util.concurrent.UncheckedExecutionException;
023
024 import java.util.Map;
025 import java.util.concurrent.ConcurrentMap;
026 import java.util.concurrent.ExecutionException;
027
028 /**
029 * A semi-persistent mapping from keys to values. Values are automatically loaded by the cache,
030 * and are stored in the cache until either evicted or manually invalidated.
031 *
032 * <p>All methods other than {@link #get} and {@link #getUnchecked} are optional.
033 *
034 * <p>When evaluated as a {@link Function}, a cache yields the same result as invoking {@link
035 * #getUnchecked}.
036 *
037 * @author Charles Fry
038 * @since 10.0
039 */
040 @Beta
041 public interface Cache<K, V> extends Function<K, V> {
042
043 /**
044 * Returns the value associated with the given key, creating or retrieving that value if
045 * necessary, and throwing an execution exception on failure. No state associated with this cache
046 * is modified until loading completes. Note that this method will never return {@code null}.
047 *
048 * @throws ExecutionException if a checked exception was thrown while loading the response
049 * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the
050 * response
051 * @throws ExecutionError if an error was thrown while loading the response
052 */
053 V get(K key) throws ExecutionException;
054
055 /**
056 * Returns the value associated with the given key, loading that value if necessary. No state
057 * associated with this cache is modified until computation completes. Unlike {@link #get}, this
058 * method does not throw a checked exception, and thus should only be used in situations where
059 * checked exceptions are not thrown by the cache loader. Note that this method will never return
060 * {@code null}.
061 *
062 * <p><b>Warning:</b> this method silently converts checked exceptions to unchecked exceptions.
063 * The {@link #get} method should be preferred for cache loaders which throw checked exceptions.
064 *
065 * @throws UncheckedExecutionException if an exception was thrown while loading the response,
066 * regardless of whether the exception was checked or unchecked
067 * @throws ExecutionError if an error was thrown while loading the response
068 */
069 V getUnchecked(K key);
070
071 /**
072 * Discouraged. Provided to satisfy the {@code Function} interface; use {@link #get} or
073 * {@link #getUnchecked} instead.
074 *
075 * @throws UncheckedExecutionException if an exception was thrown while loading the response,
076 * regardless of whether the exception was checked or unchecked
077 * @throws ExecutionError if an error was thrown while loading the response
078 */
079 @Override
080 V apply(K key);
081
082 // TODO(fry): add bulk operations
083
084 /**
085 * Discards any cached value for key {@code key}, possibly asynchronously, so that a future
086 * invocation of {@code get(key)} will result in a cache miss and reload.
087 *
088 * @throws UnsupportedOperationException if this operation is not supported by the cache
089 * implementation
090 */
091 void invalidate(Object key);
092
093 /**
094 * Discards all entries in the cache, possibly asynchronously.
095 *
096 * @throws UnsupportedOperationException if this operation is not supported by the cache
097 * implementation
098 */
099 void invalidateAll();
100
101 /**
102 * Returns the approximate number of entries in this cache.
103 *
104 * @throws UnsupportedOperationException if this operation is not supported by the cache
105 * implementation
106 */
107 long size();
108
109 /**
110 * Returns a current snapshot of this cache's cumulative statistics. All stats are initialized
111 * to zero, and are monotonically increasing over the lifetime of the cache.
112 *
113 * @throws UnsupportedOperationException if this operation is not supported by the cache
114 * implementation
115 */
116 CacheStats stats();
117
118 /**
119 * Returns a view of the entries stored in this cache as a thread-safe map. Assume that none of
120 * the returned map's optional operations will be implemented, unless otherwise specified.
121 *
122 * <p>Operations on the returned map will never cause new values to be loaded into the cache. So,
123 * unlike {@link #get} and {@link #getUnchecked}, this map's {@link Map#get get} method will
124 * always return {@code null} for a key that is not already cached.
125 *
126 * @throws UnsupportedOperationException if this operation is not supported by the cache
127 * implementation
128 */
129 ConcurrentMap<K, V> asMap();
130
131 /**
132 * Performs any pending maintenance operations needed by the cache. Exactly which activities are
133 * performed -- if any -- is implementation-dependent.
134 */
135 void cleanUp();
136 }