    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    }