com.google.common.cache.Cache Maven / Gradle / Ivy
Show all versions of guava Show documentation
/*
* 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.
*
* Implementations of this interface are expected to be thread-safe, and can be safely accessed
* by multiple concurrent threads.
*
*
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 {
/**
* 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.
*
* Warning: as with {@link CacheLoader#load}, {@code valueLoader} must not 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 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 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}.
*
* 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 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.
*
*
Iterators from the returned map are at least weakly consistent: they are safe for
* concurrent use, but if the cache is modified (including by eviction) after the iterator is
* created, it is undefined which of the changes (if any) will be reflected in that iterator.
*/
ConcurrentMap asMap();
/**
* Performs any pending maintenance operations needed by the cache. Exactly which activities are
* performed -- if any -- is implementation-dependent.
*/
void cleanUp();
}