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
017package com.google.common.cache;
018
019import com.google.common.annotations.GwtCompatible;
020import com.google.common.collect.ImmutableMap;
021import com.google.common.util.concurrent.ExecutionError;
022import com.google.common.util.concurrent.UncheckedExecutionException;
023
024import java.util.Map;
025import java.util.concurrent.Callable;
026import java.util.concurrent.ConcurrentMap;
027import java.util.concurrent.ExecutionException;
028
029import javax.annotation.Nullable;
030
031/**
032 * A semi-persistent mapping from keys to values. Cache entries are manually added using
033 * {@link #get(Object, Callable)} or {@link #put(Object, Object)}, and are stored in the cache until
034 * either evicted or manually invalidated.
035 *
036 * <p>Implementations of this interface are expected to be thread-safe, and can be safely accessed
037 * by multiple concurrent threads.
038 *
039 * @author Charles Fry
040 * @since 10.0
041 */
042@GwtCompatible
043public interface Cache<K, V> {
044
045  /**
046   * Returns the value associated with {@code key} in this cache, or {@code null} if there is no
047   * cached value for {@code key}.
048   *
049   * @since 11.0
050   */
051  @Nullable
052  V getIfPresent(Object key);
053
054  /**
055   * Returns the value associated with {@code key} in this cache, obtaining that value from
056   * {@code valueLoader} if necessary. No observable state associated with this cache is modified
057   * until loading completes. This method provides a simple substitute for the conventional
058   * "if cached, return; otherwise create, cache and return" pattern.
059   *
060   * <p><b>Warning:</b> as with {@link CacheLoader#load}, {@code valueLoader} <b>must not</b> return
061   * {@code null}; it may either return a non-null value or throw an exception.
062   *
063   * @throws ExecutionException if a checked exception was thrown while loading the value
064   * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the
065   *     value
066   * @throws ExecutionError if an error was thrown while loading the value
067   *
068   * @since 11.0
069   */
070  V get(K key, Callable<? extends V> valueLoader) throws ExecutionException;
071
072  /**
073   * Returns a map of the values associated with {@code keys} in this cache. The returned map will
074   * only contain entries which are already present in the cache.
075   *
076   * @since 11.0
077   */
078  ImmutableMap<K, V> getAllPresent(Iterable<?> keys);
079
080  /**
081   * Associates {@code value} with {@code key} in this cache. If the cache previously contained a
082   * value associated with {@code key}, the old value is replaced by {@code value}.
083   *
084   * <p>Prefer {@link #get(Object, Callable)} when using the conventional "if cached, return;
085   * otherwise create, cache and return" pattern.
086   *
087   * @since 11.0
088   */
089  void put(K key, V value);
090
091  /**
092   * Copies all of the mappings from the specified map to the cache. The effect of this call is
093   * equivalent to that of calling {@code put(k, v)} on this map once for each mapping from key
094   * {@code k} to value {@code v} in the specified map. The behavior of this operation is undefined
095   * if the specified map is modified while the operation is in progress.
096   *
097   * @since 12.0
098   */
099  void putAll(Map<? extends K,? extends V> m);
100
101  /**
102   * Discards any cached value for key {@code key}.
103   */
104  void invalidate(Object key);
105
106  /**
107   * Discards any cached values for keys {@code keys}.
108   *
109   * @since 11.0
110   */
111  void invalidateAll(Iterable<?> keys);
112
113  /**
114   * Discards all entries in the cache.
115   */
116  void invalidateAll();
117
118  /**
119   * Returns the approximate number of entries in this cache.
120   */
121  long size();
122
123  /**
124   * Returns a current snapshot of this cache's cumulative statistics. All stats are initialized
125   * to zero, and are monotonically increasing over the lifetime of the cache.
126   *
127   */
128  CacheStats stats();
129
130  /**
131   * Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to
132   * the map directly affect the cache.
133   *
134   * <p>Iterators from the returned map are at least <i>weakly consistent</i>: they are safe for
135   * concurrent use, but if the cache is modified (including by eviction) after the iterator is
136   * created, it is undefined which of the changes (if any) will be reflected in that iterator.
137   */
138  ConcurrentMap<K, V> asMap();
139
140  /**
141   * Performs any pending maintenance operations needed by the cache. Exactly which activities are
142   * performed -- if any -- is implementation-dependent.
143   */
144  void cleanUp();
145}