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.collect.ImmutableMap;
019import com.google.common.collect.Maps;
020import java.util.Map;
021import java.util.concurrent.Callable;
022import java.util.concurrent.ConcurrentMap;
023import java.util.concurrent.ExecutionException;
024
025/**
026 * This class provides a skeletal implementation of the {@code Cache} interface to minimize the
027 * effort required to implement this interface.
028 *
029 * <p>To implement a cache, the programmer needs only to extend this class and provide an
030 * implementation for the {@link #put} and {@link #getIfPresent} methods. {@link #getAllPresent} is
031 * implemented in terms of {@link #getIfPresent}; {@link #putAll} is implemented in terms of
032 * {@link #put}, {@link #invalidateAll(Iterable)} is implemented in terms of {@link #invalidate}.
033 * The method {@link #cleanUp} is a no-op. All other methods throw an
034 * {@link UnsupportedOperationException}.
035 *
036 * @author Charles Fry
037 * @since 10.0
038 */
039@GwtCompatible
040public abstract class AbstractCache<K, V> implements Cache<K, V> {
041
042  /** Constructor for use by subclasses. */
043  protected AbstractCache() {}
044
045  /**
046   * @since 11.0
047   */
048  @Override
049  public V get(K key, Callable<? extends V> valueLoader) throws ExecutionException {
050    throw new UnsupportedOperationException();
051  }
052
053  /**
054   * {@inheritDoc}
055   *
056   * <p>This implementation of {@code getAllPresent} lacks any insight into the internal cache data
057   * structure, and is thus forced to return the query keys instead of the cached keys. This is only
058   * possible with an unsafe cast which requires {@code keys} to actually be of type {@code K}.
059   *
060   * @since 11.0
061   */
062  @Override
063  public ImmutableMap<K, V> getAllPresent(Iterable<?> keys) {
064    Map<K, V> result = Maps.newLinkedHashMap();
065    for (Object key : keys) {
066      if (!result.containsKey(key)) {
067        @SuppressWarnings("unchecked")
068        K castKey = (K) key;
069        V value = getIfPresent(key);
070        if (value != null) {
071          result.put(castKey, value);
072        }
073      }
074    }
075    return ImmutableMap.copyOf(result);
076  }
077
078  /**
079   * @since 11.0
080   */
081  @Override
082  public void put(K key, V value) {
083    throw new UnsupportedOperationException();
084  }
085
086  /**
087   * @since 12.0
088   */
089  @Override
090  public void putAll(Map<? extends K, ? extends V> m) {
091    for (Map.Entry<? extends K, ? extends V> entry : m.entrySet()) {
092      put(entry.getKey(), entry.getValue());
093    }
094  }
095
096  @Override
097  public void cleanUp() {}
098
099  @Override
100  public long size() {
101    throw new UnsupportedOperationException();
102  }
103
104  @Override
105  public void invalidate(Object key) {
106    throw new UnsupportedOperationException();
107  }
108
109  /**
110   * @since 11.0
111   */
112  @Override
113  public void invalidateAll(Iterable<?> keys) {
114    for (Object key : keys) {
115      invalidate(key);
116    }
117  }
118
119  @Override
120  public void invalidateAll() {
121    throw new UnsupportedOperationException();
122  }
123
124  @Override
125  public CacheStats stats() {
126    throw new UnsupportedOperationException();
127  }
128
129  @Override
130  public ConcurrentMap<K, V> asMap() {
131    throw new UnsupportedOperationException();
132  }
133
134  /**
135   * Accumulates statistics during the operation of a {@link Cache} for presentation by
136   * {@link Cache#stats}. This is solely intended for consumption by {@code Cache} implementors.
137   *
138   * @since 10.0
139   */
140  public interface StatsCounter {
141    /**
142     * Records cache hits. This should be called when a cache request returns a cached value.
143     *
144     * @param count the number of hits to record
145     * @since 11.0
146     */
147    void recordHits(int count);
148
149    /**
150     * Records cache misses. This should be called when a cache request returns a value that was not
151     * found in the cache. This method should be called by the loading thread, as well as by threads
152     * blocking on the load. Multiple concurrent calls to {@link Cache} lookup methods with the same
153     * key on an absent value should result in a single call to either {@code recordLoadSuccess} or
154     * {@code recordLoadException} and multiple calls to this method, despite all being served by
155     * the results of a single load operation.
156     *
157     * @param count the number of misses to record
158     * @since 11.0
159     */
160    void recordMisses(int count);
161
162    /**
163     * Records the successful load of a new entry. This should be called when a cache request causes
164     * an entry to be loaded, and the loading completes successfully. In contrast to
165     * {@link #recordMisses}, this method should only be called by the loading thread.
166     *
167     * @param loadTime the number of nanoseconds the cache spent computing or retrieving the new
168     *     value
169     */
170    void recordLoadSuccess(long loadTime);
171
172    /**
173     * Records the failed load of a new entry. This should be called when a cache request causes an
174     * entry to be loaded, but an exception is thrown while loading the entry. In contrast to
175     * {@link #recordMisses}, this method should only be called by the loading thread.
176     *
177     * @param loadTime the number of nanoseconds the cache spent computing or retrieving the new
178     *     value prior to an exception being thrown
179     */
180    void recordLoadException(long loadTime);
181
182    /**
183     * Records the eviction of an entry from the cache. This should only been called when an entry
184     * is evicted due to the cache's eviction strategy, and not as a result of manual
185     * {@linkplain Cache#invalidate invalidations}.
186     */
187    void recordEviction();
188
189    /**
190     * Returns a snapshot of this counter's values. Note that this may be an inconsistent view, as
191     * it may be interleaved with update operations.
192     */
193    CacheStats snapshot();
194  }
195
196  /**
197   * A thread-safe {@link StatsCounter} implementation for use by {@link Cache} implementors.
198   *
199   * @since 10.0
200   */
201  public static final class SimpleStatsCounter implements StatsCounter {
202    private final LongAddable hitCount = LongAddables.create();
203    private final LongAddable missCount = LongAddables.create();
204    private final LongAddable loadSuccessCount = LongAddables.create();
205    private final LongAddable loadExceptionCount = LongAddables.create();
206    private final LongAddable totalLoadTime = LongAddables.create();
207    private final LongAddable evictionCount = LongAddables.create();
208
209    /**
210     * Constructs an instance with all counts initialized to zero.
211     */
212    public SimpleStatsCounter() {}
213
214    /**
215     * @since 11.0
216     */
217    @Override
218    public void recordHits(int count) {
219      hitCount.add(count);
220    }
221
222    /**
223     * @since 11.0
224     */
225    @Override
226    public void recordMisses(int count) {
227      missCount.add(count);
228    }
229
230    @Override
231    public void recordLoadSuccess(long loadTime) {
232      loadSuccessCount.increment();
233      totalLoadTime.add(loadTime);
234    }
235
236    @Override
237    public void recordLoadException(long loadTime) {
238      loadExceptionCount.increment();
239      totalLoadTime.add(loadTime);
240    }
241
242    @Override
243    public void recordEviction() {
244      evictionCount.increment();
245    }
246
247    @Override
248    public CacheStats snapshot() {
249      return new CacheStats(
250          hitCount.sum(),
251          missCount.sum(),
252          loadSuccessCount.sum(),
253          loadExceptionCount.sum(),
254          totalLoadTime.sum(),
255          evictionCount.sum());
256    }
257
258    /**
259     * Increments all counters by the values in {@code other}.
260     */
261    public void incrementBy(StatsCounter other) {
262      CacheStats otherStats = other.snapshot();
263      hitCount.add(otherStats.hitCount());
264      missCount.add(otherStats.missCount());
265      loadSuccessCount.add(otherStats.loadSuccessCount());
266      loadExceptionCount.add(otherStats.loadExceptionCount());
267      totalLoadTime.add(otherStats.totalLoadTime());
268      evictionCount.add(otherStats.evictionCount());
269    }
270  }
271}