1 files changed, 147 insertions, 0 deletions
diff --git a/guava/src/com/google/common/cache/Cache.java b/guava/src/com/google/common/cache/Cache.java
new file mode 100644
index 0000000..cfe5764
--- /dev/null
+++ b/guava/src/com/google/common/cache/Cache.java
@@ -0,0 +1,147 @@
+/*
+ * Copyright (C) 2011 The Guava Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.common.cache;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+import com.google.common.collect.ImmutableMap;
+import com.google.common.util.concurrent.ExecutionError;
+import com.google.common.util.concurrent.UncheckedExecutionException;
+
+import java.util.Map;
+import java.util.concurrent.Callable;
+import java.util.concurrent.ConcurrentMap;
+import java.util.concurrent.ExecutionException;
+
+import javax.annotation.Nullable;
+
+/**
+ * A semi-persistent mapping from keys to values. Cache entries are manually added using
+ * {@link #get(Object, Callable)} or {@link #put(Object, Object)}, and are stored in the cache until
+ * either evicted or manually invalidated.
+ *
+ * <p>Implementations of this interface are expected to be thread-safe, and can be safely accessed
+ * by multiple concurrent threads.
+ *
+ * <p>Note that while this class is still annotated as {@link Beta}, the API is frozen from a
+ * consumer's standpoint. In other words existing methods are all considered {@code non-Beta} and
+ * won't be changed without going through an 18 month deprecation cycle; however new methods may be
+ * added at any time.
+ *
+ * @author Charles Fry
+ * @since 10.0
+ */
+@Beta
+@GwtCompatible
+public interface Cache<K, V> {
+
+  /**
+   * Returns the value associated with {@code key} in this cache, or {@code null} if there is no
+   * cached value for {@code key}.
+   *
+   * @since 11.0
+   */
+  @Nullable
+  V getIfPresent(Object key);
+
+  /**
+   * Returns the value associated with {@code key} in this cache, obtaining that value from
+   * {@code valueLoader} if necessary. No observable state associated with this cache is modified
+   * until loading completes. This method provides a simple substitute for the conventional
+   * "if cached, return; otherwise create, cache and return" pattern.
+   *
+   * <p><b>Warning:</b> as with {@link CacheLoader#load}, {@code valueLoader} <b>must not</b> return
+   * {@code null}; it may either return a non-null value or throw an exception.
+   *
+   * @throws ExecutionException if a checked exception was thrown while loading the value
+   * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the
+   *     value
+   * @throws ExecutionError if an error was thrown while loading the value
+   *
+   * @since 11.0
+   */
+  V get(K key, Callable<? extends V> valueLoader) throws ExecutionException;
+
+  /**
+   * Returns a map of the values associated with {@code keys} in this cache. The returned map will
+   * only contain entries which are already present in the cache.
+   *
+   * @since 11.0
+   */
+  ImmutableMap<K, V> getAllPresent(Iterable<?> keys);
+
+  /**
+   * Associates {@code value} with {@code key} in this cache. If the cache previously contained a
+   * value associated with {@code key}, the old value is replaced by {@code value}.
+   *
+   * <p>Prefer {@link #get(Object, Callable)} when using the conventional "if cached, return;
+   * otherwise create, cache and return" pattern.
+   *
+   * @since 11.0
+   */
+  void put(K key, V value);
+
+  /**
+   * Copies all of the mappings from the specified map to the cache. The effect of this call is
+   * equivalent to that of calling {@code put(k, v)} on this map once for each mapping from key
+   * {@code k} to value {@code v} in the specified map. The behavior of this operation is undefined
+   * if the specified map is modified while the operation is in progress.
+   *
+   * @since 12.0
+   */
+  void putAll(Map<? extends K,? extends V> m);
+
+  /**
+   * Discards any cached value for key {@code key}.
+   */
+  void invalidate(Object key);
+
+  /**
+   * Discards any cached values for keys {@code keys}.
+   *
+   * @since 11.0
+   */
+  void invalidateAll(Iterable<?> keys);
+
+  /**
+   * Discards all entries in the cache.
+   */
+  void invalidateAll();
+
+  /**
+   * Returns the approximate number of entries in this cache.
+   */
+  long size();
+
+  /**
+   * Returns a current snapshot of this cache's cumulative statistics. All stats are initialized
+   * to zero, and are monotonically increasing over the lifetime of the cache.
+   */
+  CacheStats stats();
+
+  /**
+   * Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to
+   * the map directly affect the cache.
+   */
+  ConcurrentMap<K, V> asMap();
+
+  /**
+   * Performs any pending maintenance operations needed by the cache. Exactly which activities are
+   * performed -- if any -- is implementation-dependent.
+   */
+  void cleanUp();
+}