001/* 002 * Copyright (C) 2011 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.cache; 016 017import com.google.common.annotations.GwtCompatible; 018import com.google.common.base.Function; 019import com.google.common.collect.ImmutableMap; 020import com.google.common.util.concurrent.ExecutionError; 021import com.google.common.util.concurrent.UncheckedExecutionException; 022import java.util.concurrent.ConcurrentMap; 023import java.util.concurrent.ExecutionException; 024 025/** 026 * A semi-persistent mapping from keys to values. Values are automatically loaded by the cache, and 027 * are stored in the cache until either evicted or manually invalidated. The common way to build 028 * instances is using {@link CacheBuilder}. 029 * 030 * <p>Implementations of this interface are expected to be thread-safe, and can be safely accessed 031 * by multiple concurrent threads. 032 * 033 * <p>When evaluated as a {@link Function}, a cache yields the same result as invoking {@link 034 * #getUnchecked}. 035 * 036 * @param <K> the type of the cache's keys, which are not permitted to be null 037 * @param <V> the type of the cache's values, which are not permitted to be null 038 * @author Charles Fry 039 * @since 11.0 040 */ 041@GwtCompatible 042@ElementTypesAreNonnullByDefault 043public interface LoadingCache<K, V> extends Cache<K, V>, Function<K, V> { 044 045 /** 046 * Returns the value associated with {@code key} in this cache, first loading that value if 047 * necessary. No observable state associated with this cache is modified until loading completes. 048 * 049 * <p>If another call to {@link #get} or {@link #getUnchecked} is currently loading the value for 050 * {@code key}, simply waits for that thread to finish and returns its loaded value. Note that 051 * multiple threads can concurrently load values for distinct keys. 052 * 053 * <p>Caches loaded by a {@link CacheLoader} will call {@link CacheLoader#load} to load new values 054 * into the cache. Newly loaded values are added to the cache using {@code 055 * Cache.asMap().putIfAbsent} after loading has completed; if another value was associated with 056 * {@code key} while the new value was loading then a removal notification will be sent for the 057 * new value. 058 * 059 * <p>If the cache loader associated with this cache is known not to throw checked exceptions, 060 * then prefer {@link #getUnchecked} over this method. 061 * 062 * @throws ExecutionException if a checked exception was thrown while loading the value. ({@code 063 * ExecutionException} is thrown <a 064 * href="https://github.com/google/guava/wiki/CachesExplained#interruption">even if 065 * computation was interrupted by an {@code InterruptedException}</a>.) 066 * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the 067 * value 068 * @throws ExecutionError if an error was thrown while loading the value 069 */ 070 V get(K key) throws ExecutionException; 071 072 /** 073 * Returns the value associated with {@code key} in this cache, first loading that value if 074 * necessary. No observable state associated with this cache is modified until loading completes. 075 * Unlike {@link #get}, this method does not throw a checked exception, and thus should only be 076 * used in situations where checked exceptions are not thrown by the cache loader. 077 * 078 * <p>If another call to {@link #get} or {@link #getUnchecked} is currently loading the value for 079 * {@code key}, simply waits for that thread to finish and returns its loaded value. Note that 080 * multiple threads can concurrently load values for distinct keys. 081 * 082 * <p>Caches loaded by a {@link CacheLoader} will call {@link CacheLoader#load} to load new values 083 * into the cache. Newly loaded values are added to the cache using {@code 084 * Cache.asMap().putIfAbsent} after loading has completed; if another value was associated with 085 * {@code key} while the new value was loading then a removal notification will be sent for the 086 * new value. 087 * 088 * <p><b>Warning:</b> this method silently converts checked exceptions to unchecked exceptions, 089 * and should not be used with cache loaders which throw checked exceptions. In such cases use 090 * {@link #get} instead. 091 * 092 * @throws UncheckedExecutionException if an exception was thrown while loading the value. (As 093 * explained in the last paragraph above, this should be an unchecked exception only.) 094 * @throws ExecutionError if an error was thrown while loading the value 095 */ 096 V getUnchecked(K key); 097 098 /** 099 * Returns a map of the values associated with {@code keys}, creating or retrieving those values 100 * if necessary. The returned map contains entries that were already cached, combined with newly 101 * loaded entries; it will never contain null keys or values. 102 * 103 * <p>Caches loaded by a {@link CacheLoader} will issue a single request to {@link 104 * CacheLoader#loadAll} for all keys which are not already present in the cache. All entries 105 * returned by {@link CacheLoader#loadAll} will be stored in the cache, over-writing any 106 * previously cached values. This method will throw an exception if {@link CacheLoader#loadAll} 107 * returns {@code null}, returns a map containing null keys or values, or fails to return an entry 108 * for each requested key. 109 * 110 * <p>Note that duplicate elements in {@code keys}, as determined by {@link Object#equals}, will 111 * be ignored. 112 * 113 * @throws ExecutionException if a checked exception was thrown while loading the value. ({@code 114 * ExecutionException} is thrown <a 115 * href="https://github.com/google/guava/wiki/CachesExplained#interruption">even if 116 * computation was interrupted by an {@code InterruptedException}</a>.) 117 * @throws UncheckedExecutionException if an unchecked exception was thrown while loading the 118 * values 119 * @throws ExecutionError if an error was thrown while loading the values 120 * @since 11.0 121 */ 122 ImmutableMap<K, V> getAll(Iterable<? extends K> keys) throws ExecutionException; 123 124 /** 125 * @deprecated Provided to satisfy the {@code Function} interface; use {@link #get} or {@link 126 * #getUnchecked} instead. 127 * @throws UncheckedExecutionException if an exception was thrown while loading the value. (As 128 * described in the documentation for {@link #getUnchecked}, {@code LoadingCache} should be 129 * used as a {@code Function} only with cache loaders that throw only unchecked exceptions.) 130 */ 131 @Deprecated 132 @Override 133 V apply(K key); 134 135 /** 136 * Loads a new value for {@code key}, possibly asynchronously. While the new value is loading the 137 * previous value (if any) will continue to be returned by {@code get(key)} unless it is evicted. 138 * If the new value is loaded successfully it will replace the previous value in the cache; if an 139 * exception is thrown while refreshing the previous value will remain, <i>and the exception will 140 * be logged (using {@link java.util.logging.Logger}) and swallowed</i>. 141 * 142 * <p>Caches loaded by a {@link CacheLoader} will call {@link CacheLoader#reload} if the cache 143 * currently contains a value for {@code key}, and {@link CacheLoader#load} otherwise. Loading is 144 * asynchronous only if {@link CacheLoader#reload} was overridden with an asynchronous 145 * implementation. 146 * 147 * <p>Returns without doing anything if another thread is currently loading the value for {@code 148 * key}. If the cache loader associated with this cache performs refresh asynchronously then this 149 * method may return before refresh completes. 150 * 151 * @since 11.0 152 */ 153 void refresh(K key); 154 155 /** 156 * {@inheritDoc} 157 * 158 * <p><b>Note that although the view <i>is</i> modifiable, no method on the returned map will ever 159 * cause entries to be automatically loaded.</b> 160 */ 161 @Override 162 ConcurrentMap<K, V> asMap(); 163}