    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.annotations.GwtCompatible;
    021    import com.google.common.collect.ImmutableMap;
    022    import com.google.common.util.concurrent.ExecutionError;
    023    import com.google.common.util.concurrent.UncheckedExecutionException;
    024
    025    import java.util.Map;
    026    import java.util.concurrent.Callable;
    027    import java.util.concurrent.ConcurrentMap;
    028    import java.util.concurrent.ExecutionException;
    029
    030    import javax.annotation.Nullable;
    031
    032    /**
    033     * A semi-persistent mapping from keys to values. Cache entries are manually added using
    034     * {@link #get(Object, Callable)} or {@link #put(Object, Object)}, and are stored in the cache until
    035     * either evicted or manually invalidated.
    036     *
    037     * <p>Implementations of this interface are expected to be thread-safe, and can be safely accessed
    038     * by multiple concurrent threads.
    039     *
    040     * <p>Note that while this class is still annotated as {@link Beta}, the API is frozen from a
    041     * consumer's standpoint. In other words existing methods are all considered {@code non-Beta} and
    042     * won't be changed without going through an 18 month deprecation cycle; however new methods may be
    043     * added at any time.
    044     *
    045     * @author Charles Fry
    046     * @since 10.0
    047     */
    048    @Beta
    049    @GwtCompatible
    050    public interface Cache<K, V> {
    051
    052      /**
    053       * Returns the value associated with {@code key} in this cache, or {@code null} if there is no
    054       * cached value for {@code key}.
    055       *
    056       * @since 11.0
    057       */
    058      @Nullable
    059      V getIfPresent(Object key);
    060
    061      /**
    062       * Returns the value associated with {@code key} in this cache, obtaining that value from
    063       * {@code valueLoader} if necessary. No observable state associated with this cache is modified
    064       * until loading completes. This method provides a simple substitute for the conventional
    065       * "if cached, return; otherwise create, cache and return" pattern.
    066       *
    067       * <p><b>Warning:</b> as with {@link CacheLoader#load}, {@code valueLoader} <b>must not</b> return
    068       * {@code null}; it may either return a non-null value or throw an exception.
    069       *
    070       * @throws ExecutionException if a checked exception was thrown while loading the value
    071       * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the
    072       *     value
    073       * @throws ExecutionError if an error was thrown while loading the value
    074       *
    075       * @since 11.0
    076       */
    077      V get(K key, Callable<? extends V> valueLoader) throws ExecutionException;
    078
    079      /**
    080       * Returns a map of the values associated with {@code keys} in this cache. The returned map will
    081       * only contain entries which are already present in the cache.
    082       *
    083       * @since 11.0
    084       */
    085      ImmutableMap<K, V> getAllPresent(Iterable<?> keys);
    086
    087      /**
    088       * Associates {@code value} with {@code key} in this cache. If the cache previously contained a
    089       * value associated with {@code key}, the old value is replaced by {@code value}.
    090       *
    091       * <p>Prefer {@link #get(Object, Callable)} when using the conventional "if cached, return;
    092       * otherwise create, cache and return" pattern.
    093       *
    094       * @since 11.0
    095       */
    096      void put(K key, V value);
    097
    098      /**
    099       * 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      CacheStats stats();
    135
    136      /**
    137       * Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to
    138       * the map directly affect the cache.
    139       */
    140      ConcurrentMap<K, V> asMap();
    141
    142      /**
    143       * Performs any pending maintenance operations needed by the cache. Exactly which activities are
    144       * performed -- if any -- is implementation-dependent.
    145       */
    146      void cleanUp();
    147    }