/*
* Copyright 2014 Ben Manes. All Rights Reserved.
*
* 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.github.benmanes.caffeine.cache;
import static java.util.Objects.requireNonNull;
import java.lang.ref.SoftReference;
import java.lang.ref.WeakReference;
import java.util.ConcurrentModificationException;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.Executor;
import java.util.concurrent.ForkJoinPool;
import java.util.concurrent.RejectedExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.function.Supplier;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.annotation.Nonnegative;
import javax.annotation.Nonnull;
import com.github.benmanes.caffeine.cache.Async.AsyncExpiry;
import com.github.benmanes.caffeine.cache.Async.AsyncRemovalListener;
import com.github.benmanes.caffeine.cache.Async.AsyncWeigher;
import com.github.benmanes.caffeine.cache.stats.CacheStats;
import com.github.benmanes.caffeine.cache.stats.ConcurrentStatsCounter;
import com.github.benmanes.caffeine.cache.stats.StatsCounter;
/**
* A builder of {@link AsyncLoadingCache}, {@link LoadingCache}, and {@link Cache} instances
* having a combination of the following features:
* <ul>
* <li>automatic loading of entries into the cache, optionally asynchronously
* <li>size-based eviction when a maximum is exceeded based on frequency and recency
* <li>time-based expiration of entries, measured since last access or last write
* <li>asynchronously refresh when the first stale request for an entry occurs
* <li>keys automatically wrapped in {@linkplain WeakReference weak} references
* <li>values automatically wrapped in {@linkplain WeakReference weak} or
* {@linkplain SoftReference soft} references
* <li>writes propagated to an external resource
* <li>notification of evicted (or otherwise removed) entries
* <li>accumulation of cache access statistics
* </ul>
* <p>
* These features are all optional; caches can be created using all or none of them. By default
* cache instances created by {@code Caffeine} will not perform any type of eviction.
* <p>
* Usage example:
* <pre>{@code
* LoadingCache<Key, Graph> graphs = Caffeine.newBuilder()
* .maximumSize(10_000)
* .expireAfterWrite(10, TimeUnit.MINUTES)
* .removalListener((Key key, Graph graph, RemovalCause cause) ->
* System.out.printf("Key %s was removed (%s)%n", key, cause))
* .build(key -> createExpensiveGraph(key));
* }</pre>
* <p>
* The returned cache is implemented as a hash table with similar performance characteristics to
* {@link ConcurrentHashMap}. The {@code asMap} view (and its collection views) have <i>weakly
* consistent iterators</i>. This means that they are safe for concurrent use, but if other threads
* modify the cache after the iterator is created, it is undefined which of these changes, if any,
* are reflected in that iterator. These iterators never throw
* {@link ConcurrentModificationException}.
* <p>
* <b>Note:</b> by default, the returned cache uses equality comparisons (the
* {@link Object#equals equals} method) to determine equality for keys or values. However, if
* {@link #weakKeys} was specified, the cache uses identity ({@code ==}) comparisons instead for
* keys. Likewise, if {@link #weakValues} or {@link #softValues} was specified, the cache uses
* identity comparisons for values.
* <p>
* Entries are automatically evicted from the cache when any of
* {@linkplain #maximumSize(long) maximumSize}, {@linkplain #maximumWeight(long) maximumWeight},
* {@linkplain #expireAfter(Expiry) expireAfter}, {@linkplain #expireAfterWrite expireAfterWrite},
* {@linkplain #expireAfterAccess expireAfterAccess}, {@linkplain #weakKeys weakKeys},
* {@linkplain #weakValues weakValues}, or {@linkplain #softValues softValues} are requested.
* <p>
* If {@linkplain #maximumSize(long) maximumSize} or {@linkplain #maximumWeight(long) maximumWeight}
* is requested entries may be evicted on each cache modification.
* <p>
* If {@linkplain #expireAfter(Expiry) expireAfter},
* {@linkplain #expireAfterWrite expireAfterWrite}, or
* {@linkplain #expireAfterAccess expireAfterAccess} is requested entries may be evicted on each
* cache modification, on occasional cache accesses, or on calls to {@link Cache#cleanUp}. Expired
* entries may be counted by {@link Cache#estimatedSize()}, but will never be visible to read or
* write operations.
* <p>
* If {@linkplain #weakKeys weakKeys}, {@linkplain #weakValues weakValues}, or
* {@linkplain #softValues softValues} are requested, it is possible for a key or value present in
* the cache to be reclaimed by the garbage collector. Entries with reclaimed keys or values may be
* removed from the cache on each cache modification, on occasional cache accesses, or on calls to
* {@link Cache#cleanUp}; such entries may be counted in {@link Cache#estimatedSize()}, but will
* never be visible to read or write operations.
* <p>
* Certain cache configurations will result in the accrual of periodic maintenance tasks which
* will be performed during write operations, or during occasional read operations in the absence of
* writes. The {@link Cache#cleanUp} method of the returned cache will also perform maintenance, but
* calling it should not be necessary with a high throughput cache. Only caches built with
* {@linkplain #maximumSize maximumSize}, {@linkplain #maximumWeight maximumWeight},
* {@linkplain #expireAfter(Expiry) expireAfter}, {@linkplain #expireAfterWrite expireAfterWrite},
* {@linkplain #expireAfterAccess expireAfterAccess}, {@linkplain #weakKeys weakKeys},
* {@linkplain #weakValues weakValues}, or {@linkplain #softValues softValues} perform periodic
* maintenance.
* <p>
* The caches produced by {@code Caffeine} are serializable, and the deserialized caches retain all
* the configuration properties of the original cache. Note that the serialized form does <i>not</i>
* include cache contents, but only configuration.
*
* @author ben.manes@gmail.com (Ben Manes)
* @param <K> the base key type for all caches created by this builder
* @param <V> the base value type for all caches created by this builder
*/
@SuppressWarnings("PMD.TooManyFields")
public final class Caffeine<K, V> {
static final Logger logger = Logger.getLogger(Caffeine.class.getName());
static final Supplier<StatsCounter> ENABLED_STATS_COUNTER_SUPPLIER = ConcurrentStatsCounter::new;
enum Strength { WEAK, SOFT }
static final int UNSET_INT = -1;
static final int DEFAULT_INITIAL_CAPACITY = 0;
static final int DEFAULT_EXPIRATION_NANOS = 0;
static final int DEFAULT_REFRESH_NANOS = 0;
boolean strictParsing = true;
long maximumSize = UNSET_INT;
long maximumWeight = UNSET_INT;
int initialCapacity = UNSET_INT;
long refreshNanos = UNSET_INT;
long expireAfterWriteNanos = UNSET_INT;
long expireAfterAccessNanos = UNSET_INT;
RemovalListener<? super K, ? super V> removalListener;
Supplier<StatsCounter> statsCounterSupplier;
CacheWriter<? super K, ? super V> writer;
Weigher<? super K, ? super V> weigher;
Expiry<? super K, ? super V> expiry;
Executor executor;
Ticker ticker;
Strength keyStrength;
Strength valueStrength;
private Caffeine() {}
/** Ensures that the argument expression is true. */
static void requireArgument(boolean expression, String template, Object... args) {
if (!expression) {
throw new IllegalArgumentException(String.format(template, args));
}
}
/** Ensures that the argument expression is true. */
static void requireArgument(boolean expression) {
if (!expression) {
throw new IllegalArgumentException();
}
}
/** Ensures that the state expression is true. */
static void requireState(boolean expression) {
if (!expression) {
throw new IllegalStateException();
}
}
/** Ensures that the state expression is true. */
static void requireState(boolean expression, String template, Object... args) {
if (!expression) {
throw new IllegalStateException(String.format(template, args));
}
}
/**
* Constructs a new {@code Caffeine} instance with default settings, including strong keys, strong
* values, and no automatic eviction of any kind.
*
* @return a new instance with default settings
*/
@Nonnull
public static Caffeine<Object, Object> newBuilder() {
return new Caffeine<>();
}
/**
* Constructs a new {@code Caffeine} instance with the settings specified in {@code spec}.
*
* @param spec the specification to build from
* @return a new instance with the specification's settings
*/
@Nonnull
public static Caffeine<Object, Object> from(CaffeineSpec spec) {
Caffeine<Object, Object> builder = spec.toBuilder();
builder.strictParsing = false;
return builder;
}
/**
* Constructs a new {@code Caffeine} instance with the settings specified in {@code spec}.
*
* @param spec a String in the format specified by {@link CaffeineSpec}
* @return a new instance with the specification's settings
*/
@Nonnull
public static Caffeine<Object, Object> from(String spec) {
return from(CaffeineSpec.parse(spec));
}
/**
* Sets the minimum total size for the internal data structures. Providing a large enough estimate
* at construction time avoids the need for expensive resizing operations later, but setting this
* value unnecessarily high wastes memory.
*
* @param initialCapacity minimum total size for the internal data structures
* @return this builder instance
* @throws IllegalArgumentException if {@code initialCapacity} is negative
* @throws IllegalStateException if an initial capacity was already set
*/
@Nonnull
public Caffeine<K, V> initialCapacity(@Nonnegative int initialCapacity) {
requireState(this.initialCapacity == UNSET_INT,
"initial capacity was already set to %s", this.initialCapacity);
requireArgument(initialCapacity >= 0);
this.initialCapacity = initialCapacity;
return this;
}
boolean hasInitialCapacity() {
return (initialCapacity != UNSET_INT);
}
int getInitialCapacity() {
return hasInitialCapacity() ? initialCapacity : DEFAULT_INITIAL_CAPACITY;
}
/**
* Specifies the executor to use when running asynchronous tasks. The executor is delegated to
* when sending removal notifications, when asynchronous computations are performed by
* {@link AsyncLoadingCache} or {@link LoadingCache#refresh} or {@link #refreshAfterWrite}, or
* when performing periodic maintenance. By default, {@link ForkJoinPool#commonPool()} is used.
* <p>
* The primary intent of this method is to facilitate testing of caches which have been
* configured with {@link #removalListener} or utilize asynchronous computations. A test may
* instead prefer to configure the cache to execute tasks directly on the same thread.
* <p>
* Beware that configuring a cache with an executor that throws {@link RejectedExecutionException}
* may experience non-deterministic behavior.
*
* @param executor the executor to use for asynchronous execution
* @return this builder instance
* @throws NullPointerException if the specified executor is null
*/
@Nonnull
public Caffeine<K, V> executor(@Nonnull Executor executor) {
requireState(this.executor == null, "executor was already set to %s", this.executor);
this.executor = requireNonNull(executor);
return this;
}
@Nonnull
Executor getExecutor() {
return (executor == null) ? ForkJoinPool.commonPool() : executor;
}
/**
* Specifies the maximum number of entries the cache may contain. Note that the cache <b>may evict
* an entry before this limit is exceeded or temporarily exceed the threshold while evicting</b>.
* As the cache size grows close to the maximum, the cache evicts entries that are less likely to
* be used again. For example, the cache may evict an entry because it hasn't been used recently
* or very often.
* <p>
* When {@code size} is zero, elements will be evicted immediately after being loaded into the
* cache. This can be useful in testing, or to disable caching temporarily without a code change.
* <p>
* This feature cannot be used in conjunction with {@link #maximumWeight}.
*
* @param maximumSize the maximum size of the cache
* @return this builder instance
* @throws IllegalArgumentException if {@code size} is negative
* @throws IllegalStateException if a maximum size or weight was already set
*/
@Nonnull
public Caffeine<K, V> maximumSize(@Nonnegative long maximumSize) {
requireState(this.maximumSize == UNSET_INT,
"maximum size was already set to %s", this.maximumSize);
requireState(this.maximumWeight == UNSET_INT,
"maximum weight was already set to %s", this.maximumWeight);
requireState(this.weigher == null, "maximum size can not be combined with weigher");
requireArgument(maximumSize >= 0, "maximum size must not be negative");
this.maximumSize = maximumSize;
return this;
}
/**
* Specifies the maximum weight of entries the cache may contain. Weight is determined using the
* {@link Weigher} specified with {@link #weigher}, and use of this method requires a
* corresponding call to {@link #weigher} prior to calling {@link #build}.
* <p>
* Note that the cache <b>may evict an entry before this limit is exceeded or temporarily exceed
* the threshold while evicting</b>. As the cache size grows close to the maximum, the cache
* evicts entries that are less likely to be used again. For example, the cache may evict an entry
* because it hasn't been used recently or very often.
* <p>
* When {@code maximumWeight} is zero, elements will be evicted immediately after being loaded
* into cache. This can be useful in testing, or to disable caching temporarily without a code
* change.
* <p>
* Note that weight is only used to determine whether the cache is over capacity; it has no effect
* on selecting which entry should be evicted next.
* <p>
* This feature cannot be used in conjunction with {@link #maximumSize}.
*
* @param maximumWeight the maximum total weight of entries the cache may contain
* @return this builder instance
* @throws IllegalArgumentException if {@code maximumWeight} is negative
* @throws IllegalStateException if a maximum weight or size was already set
*/
@Nonnull
public Caffeine<K, V> maximumWeight(@Nonnegative long maximumWeight) {
requireState(this.maximumWeight == UNSET_INT,
"maximum weight was already set to %s", this.maximumWeight);
requireState(this.maximumSize == UNSET_INT,
"maximum size was already set to %s", this.maximumSize);
this.maximumWeight = maximumWeight;
requireArgument(maximumWeight >= 0, "maximum weight must not be negative");
return this;
}
/**
* Specifies the weigher to use in determining the weight of entries. Entry weight is taken into
* consideration by {@link #maximumWeight(long)} when determining which entries to evict, and use
* of this method requires a corresponding call to {@link #maximumWeight(long)} prior to calling
* {@link #build}. Weights are measured and recorded when entries are inserted into or updated in
* the cache, and are thus effectively static during the lifetime of a cache entry.
* <p>
* When the weight of an entry is zero it will not be considered for size-based eviction (though
* it still may be evicted by other means).
* <p>
* <b>Important note:</b> Instead of returning <em>this</em> as a {@code Caffeine} instance, this
* method returns {@code Caffeine<K1, V1>}. From this point on, either the original reference or
* the returned reference may be used to complete configuration and build the cache, but only the
* "generic" one is type-safe. That is, it will properly prevent you from building caches whose
* key or value types are incompatible with the types accepted by the weigher already provided;
* the {@code Caffeine} type cannot do this. For best results, simply use the standard
* method-chaining idiom, as illustrated in the documentation at top, configuring a
* {@code Caffeine} and building your {@link Cache} all in a single statement.
* <p>
* <b>Warning:</b> if you ignore the above advice, and use this {@code Caffeine} to build a cache
* whose key or value type is incompatible with the weigher, you will likely experience a
* {@link ClassCastException} at some <i>undefined</i> point in the future.
*
* @param weigher the weigher to use in calculating the weight of cache entries
* @param <K1> key type of the weigher
* @param <V1> value type of the weigher
* @return the cache builder reference that should be used instead of {@code this} for any
* remaining configuration and cache building
* @throws IllegalStateException if a weigher was already set
*/
@Nonnull
public <K1 extends K, V1 extends V> Caffeine<K1, V1> weigher(
@Nonnull Weigher<? super K1, ? super V1> weigher) {
requireNonNull(weigher);
requireState(this.weigher == null, "weigher was already set to %s", this.weigher);
requireState(!strictParsing || this.maximumSize == UNSET_INT,
"weigher can not be combined with maximum size", this.maximumSize);
@SuppressWarnings("unchecked")
Caffeine<K1, V1> self = (Caffeine<K1, V1>) this;
self.weigher = weigher;
return self;
}
boolean evicts() {
return getMaximum() != UNSET_INT;
}
boolean isWeighted() {
return (weigher != null);
}
@Nonnegative
long getMaximum() {
return isWeighted() ? maximumWeight : maximumSize;
}
@Nonnull @SuppressWarnings({"unchecked", "rawtypes"})
<K1 extends K, V1 extends V> Weigher<K1, V1> getWeigher(boolean isAsync) {
Weigher<K1, V1> delegate = isWeighted() && (weigher != Weigher.singletonWeigher())
? Weigher.boundedWeigher((Weigher<K1, V1>) weigher)
: Weigher.singletonWeigher();
return isAsync ? (Weigher<K1, V1>) new AsyncWeigher(delegate) : delegate;
}
/**
* Specifies that each key (not value) stored in the cache should be wrapped in a
* {@link WeakReference} (by default, strong references are used).
* <p>
* <b>Warning:</b> when this method is used, the resulting cache will use identity ({@code ==})
* comparison to determine equality of keys.
* <p>
* Entries with keys that have been garbage collected may be counted in
* {@link Cache#estimatedSize()}, but will never be visible to read or write operations; such
* entries are cleaned up as part of the routine maintenance described in the class javadoc.
* <p>
* This feature cannot be used in conjunction with {@link #writer}.
*
* @return this builder instance
* @throws IllegalStateException if the key strength was already set or the writer was set
*/
@Nonnull
public Caffeine<K, V> weakKeys() {
requireState(keyStrength == null, "Key strength was already set to %s", keyStrength);
requireState(writer == null, "Weak keys may not be used with CacheWriter");
keyStrength = Strength.WEAK;
return this;
}
boolean isStrongKeys() {
return (keyStrength == null);
}
/**
* Specifies that each value (not key) stored in the cache should be wrapped in a
* {@link WeakReference} (by default, strong references are used).
* <p>
* Weak values will be garbage collected once they are weakly reachable. This makes them a poor
* candidate for caching; consider {@link #softValues} instead.
* <p>
* <b>Note:</b> when this method is used, the resulting cache will use identity ({@code ==})
* comparison to determine equality of values.
* <p>
* Entries with values that have been garbage collected may be counted in
* {@link Cache#estimatedSize()}, but will never be visible to read or write operations; such
* entries are cleaned up as part of the routine maintenance described in the class javadoc.
* <p>
* This feature cannot be used in conjunction with {@link #buildAsync}.
*
* @return this builder instance
* @throws IllegalStateException if the value strength was already set
*/
@Nonnull
public Caffeine<K, V> weakValues() {
requireState(valueStrength == null, "Value strength was already set to %s", valueStrength);
valueStrength = Strength.WEAK;
return this;
}
boolean isStrongValues() {
return (valueStrength == null);
}
boolean isWeakValues() {
return (valueStrength == Strength.WEAK);
}
/**
* Specifies that each value (not key) stored in the cache should be wrapped in a
* {@link SoftReference} (by default, strong references are used). Softly-referenced objects will
* be garbage-collected in a <i>globally</i> least-recently-used manner, in response to memory
* demand.
* <p>
* <b>Warning:</b> in most circumstances it is better to set a per-cache
* {@linkplain #maximumSize(long) maximum size} instead of using soft references. You should only
* use this method if you are very familiar with the practical consequences of soft references.
* <p>
* <b>Note:</b> when this method is used, the resulting cache will use identity ({@code ==})
* comparison to determine equality of values.
* <p>
* Entries with values that have been garbage collected may be counted in
* {@link Cache#estimatedSize()}, but will never be visible to read or write operations; such
* entries are cleaned up as part of the routine maintenance described in the class javadoc.
* <p>
* This feature cannot be used in conjunction with {@link #buildAsync}.
*
* @return this builder instance
* @throws IllegalStateException if the value strength was already set
*/
@Nonnull
public Caffeine<K, V> softValues() {
requireState(valueStrength == null, "Value strength was already set to %s", valueStrength);
valueStrength = Strength.SOFT;
return this;
}
/**
* Specifies that each entry should be automatically removed from the cache once a fixed duration
* has elapsed after the entry's creation, or the most recent replacement of its value.
* <p>
* Expired entries may be counted in {@link Cache#estimatedSize()}, but will never be visible to
* read or write operations. Expired entries are cleaned up as part of the routine maintenance
* described in the class javadoc.
*
* @param duration the length of time after an entry is created that it should be automatically
* removed
* @param unit the unit that {@code duration} is expressed in
* @return this builder instance
* @throws IllegalArgumentException if {@code duration} is negative
* @throws IllegalStateException if the time to live or variable expiration was already set
*/
@Nonnull
public Caffeine<K, V> expireAfterWrite(@Nonnegative long duration, @Nonnull TimeUnit unit) {
requireState(expireAfterWriteNanos == UNSET_INT,
"expireAfterWrite was already set to %s ns", expireAfterWriteNanos);
requireState(expiry == null, "expireAfterAccess may not be used with variable expiration");
requireArgument(duration >= 0, "duration cannot be negative: %s %s", duration, unit);
this.expireAfterWriteNanos = unit.toNanos(duration);
return this;
}
@Nonnegative
long getExpiresAfterWriteNanos() {
return expiresAfterWrite() ? expireAfterWriteNanos : DEFAULT_EXPIRATION_NANOS;
}
boolean expiresAfterWrite() {
return (expireAfterWriteNanos != UNSET_INT);
}
/**
* Specifies that each entry should be automatically removed from the cache once a fixed duration
* has elapsed after the entry's creation, the most recent replacement of its value, or its last
* read. Access time is reset by all cache read and write operations (including
* {@code Cache.asMap().get(Object)} and {@code Cache.asMap().put(K, V)}), but not by operations
* on the collection-views of {@link Cache#asMap}.
* <p>
* Expired entries may be counted in {@link Cache#estimatedSize()}, but will never be visible to
* read or write operations. Expired entries are cleaned up as part of the routine maintenance
* described in the class javadoc.
*
* @param duration the length of time after an entry is last accessed that it should be
* automatically removed
* @param unit the unit that {@code duration} is expressed in
* @return this builder instance
* @throws IllegalArgumentException if {@code duration} is negative
* @throws IllegalStateException if the time to idle or variable expiration was already set
*/
@Nonnull
public Caffeine<K, V> expireAfterAccess(@Nonnegative long duration, @Nonnull TimeUnit unit) {
requireState(expireAfterAccessNanos == UNSET_INT,
"expireAfterAccess was already set to %s ns", expireAfterAccessNanos);
requireState(expiry == null, "expireAfterAccess may not be used with variable expiration");
requireArgument(duration >= 0, "duration cannot be negative: %s %s", duration, unit);
this.expireAfterAccessNanos = unit.toNanos(duration);
return this;
}
@Nonnegative
long getExpiresAfterAccessNanos() {
return expiresAfterAccess() ? expireAfterAccessNanos : DEFAULT_EXPIRATION_NANOS;
}
boolean expiresAfterAccess() {
return (expireAfterAccessNanos != UNSET_INT);
}
/**
* Specifies that each entry should be automatically removed from the cache once a duration has
* elapsed after the entry's creation, the most recent replacement of its value, or its last
* read. The expiration time is reset by all cache read and write operations (including
* {@code Cache.asMap().get(Object)} and {@code Cache.asMap().put(K, V)}), but not by operations
* on the collection-views of {@link Cache#asMap}.
* <p>
* Expired entries may be counted in {@link Cache#estimatedSize()}, but will never be visible to
* read or write operations. Expired entries are cleaned up as part of the routine maintenance
* described in the class javadoc.
*
* @param expiry the expiry to use in calculating the expiration time of cache entries
* @param <K1> key type of the weigher
* @param <V1> value type of the weigher
* @return this builder instance
* @throws IllegalStateException if expiration was already set
*/
@Nonnull
public <K1 extends K, V1 extends V> Caffeine<K1, V1> expireAfter(
@Nonnull Expiry<? super K1, ? super V1> expiry) {
requireNonNull(expiry);
requireState(this.expiry == null, "Expiry was already set to %s", this.expiry);
requireState(this.expireAfterAccessNanos == UNSET_INT,
"Expiry may not be used with expiresAfterAccess");
requireState(this.expireAfterWriteNanos == UNSET_INT,
"Expiry may not be used with expiresAfterWrite");
@SuppressWarnings("unchecked")
Caffeine<K1, V1> self = (Caffeine<K1, V1>) this;
self.expiry = expiry;
return self;
}
boolean expiresVariable() {
return expiry != null;
}
@SuppressWarnings("unchecked")
Expiry<K, V> getExpiry(boolean isAsync) {
return isAsync && (expiry != null)
? (Expiry<K, V>) new AsyncExpiry<>(expiry)
: (Expiry<K, V>) expiry;
}
/**
* Specifies that active entries are eligible for automatic refresh once a fixed duration has
* elapsed after the entry's creation, or the most recent replacement of its value. The semantics
* of refreshes are specified in {@link LoadingCache#refresh}, and are performed by calling
* {@link CacheLoader#reload}.
* <p>
* Automatic refreshes are performed when the first stale request for an entry occurs. The request
* triggering refresh will make an asynchronous call to {@link CacheLoader#reload} and immediately
* return the old value.
* <p>
* <b>Note:</b> <i>all exceptions thrown during refresh will be logged and then swallowed</i>.
*
* @param duration the length of time after an entry is created that it should be considered
* stale, and thus eligible for refresh
* @param unit the unit that {@code duration} is expressed in
* @return this builder instance
* @throws IllegalArgumentException if {@code duration} is negative
* @throws IllegalStateException if the refresh interval was already set
*/
@Nonnull
public Caffeine<K, V> refreshAfterWrite(@Nonnegative long duration, @Nonnull TimeUnit unit) {
requireNonNull(unit);
requireState(refreshNanos == UNSET_INT, "refresh was already set to %s ns", refreshNanos);
requireArgument(duration > 0, "duration must be positive: %s %s", duration, unit);
this.refreshNanos = unit.toNanos(duration);
return this;
}
@Nonnegative
long getRefreshAfterWriteNanos() {
return refreshes() ? refreshNanos : DEFAULT_REFRESH_NANOS;
}
boolean refreshes() {
return refreshNanos != UNSET_INT;
}
/**
* Specifies a nanosecond-precision time source for use in determining when entries should be
* expired or refreshed. By default, {@link System#nanoTime} is used.
* <p>
* The primary intent of this method is to facilitate testing of caches which have been configured
* with {@link #expireAfterWrite}, {@link #expireAfterAccess}, or {@link #refreshAfterWrite}.
*
* @param ticker a nanosecond-precision time source
* @return this builder instance
* @throws IllegalStateException if a ticker was already set
* @throws NullPointerException if the specified ticker is null
*/
@Nonnull
public Caffeine<K, V> ticker(@Nonnull Ticker ticker) {
requireState(this.ticker == null, "Ticker was already set to %s", this.ticker);
this.ticker = requireNonNull(ticker);
return this;
}
@Nonnull
Ticker getTicker() {
boolean useTicker = expiresVariable() || expiresAfterAccess()
|| expiresAfterWrite() || refreshes() || isRecordingStats();
return useTicker
? (ticker == null) ? Ticker.systemTicker() : ticker
: Ticker.disabledTicker();
}
/**
* Specifies a listener instance that caches should notify each time an entry is removed for any
* {@linkplain RemovalCause reason}. Each cache created by this builder will invoke this listener
* as part of the routine maintenance described in the class documentation above.
* <p>
* <b>Warning:</b> after invoking this method, do not continue to use <i>this</i> cache builder
* reference; instead use the reference this method <i>returns</i>. At runtime, these point to the
* same instance, but only the returned reference has the correct generic type information so as
* to ensure type safety. For best results, use the standard method-chaining idiom illustrated in
* the class documentation above, configuring a builder and building your cache in a single
* statement. Failure to heed this advice can result in a {@link ClassCastException} being thrown
* by a cache operation at some <i>undefined</i> point in the future.
* <p>
* <b>Warning:</b> any exception thrown by {@code listener} will <i>not</i> be propagated to the
* {@code Cache} user, only logged via a {@link Logger}.
*
* @param removalListener a listener instance that caches should notify each time an entry is
* removed
* @param <K1> the key type of the listener
* @param <V1> the value type of the listener
* @return the cache builder reference that should be used instead of {@code this} for any
* remaining configuration and cache building
* @throws IllegalStateException if a removal listener was already set
* @throws NullPointerException if the specified removal listener is null
*/
@Nonnull
public <K1 extends K, V1 extends V> Caffeine<K1, V1> removalListener(
@Nonnull RemovalListener<? super K1, ? super V1> removalListener) {
requireState(this.removalListener == null);
@SuppressWarnings("unchecked")
Caffeine<K1, V1> self = (Caffeine<K1, V1>) this;
self.removalListener = requireNonNull(removalListener);
return self;
}
@SuppressWarnings({"unchecked", "rawtypes"})
<K1 extends K, V1 extends V> RemovalListener<K1, V1> getRemovalListener(boolean async) {
RemovalListener<K1, V1> castedListener = (RemovalListener<K1, V1>) removalListener;
return async && (castedListener != null)
? new AsyncRemovalListener(castedListener, getExecutor())
: castedListener;
}
/**
* Specifies a writer instance that caches should notify each time an entry is explicitly created
* or modified, or removed for any {@linkplain RemovalCause reason}. The writer is not notified
* when an entry is loaded or computed. Each cache created by this builder will invoke this writer
* as part of the atomic operation that modifies the cache.
* <p>
* <b>Warning:</b> after invoking this method, do not continue to use <i>this</i> cache builder
* reference; instead use the reference this method <i>returns</i>. At runtime, these point to the
* same instance, but only the returned reference has the correct generic type information so as
* to ensure type safety. For best results, use the standard method-chaining idiom illustrated in
* the class documentation above, configuring a builder and building your cache in a single
* statement. Failure to heed this advice can result in a {@link ClassCastException} being thrown
* by a cache operation at some <i>undefined</i> point in the future.
* <p>
* <b>Warning:</b> any exception thrown by {@code writer} will be propagated to the {@code Cache}
* user.
* <p>
* This feature cannot be used in conjunction with {@link #weakKeys()} or {@link #buildAsync}.
*
* @param writer a writer instance that caches should notify each time an entry is explicitly
* created or modified, or removed for any reason
* @param <K1> the key type of the writer
* @param <V1> the value type of the writer
* @return the cache builder reference that should be used instead of {@code this} for any
* remaining configuration and cache building
* @throws IllegalStateException if a writer was already set or if the key strength is weak
* @throws NullPointerException if the specified writer is null
*/
@Nonnull
public <K1 extends K, V1 extends V> Caffeine<K1, V1> writer(
@Nonnull CacheWriter<? super K1, ? super V1> writer) {
requireState(this.writer == null, "Writer was already set to %s", this.writer);
requireState(keyStrength == null, "Weak keys may not be used with CacheWriter");
@SuppressWarnings("unchecked")
Caffeine<K1, V1> self = (Caffeine<K1, V1>) this;
self.writer = requireNonNull(writer);
return self;
}
<K1 extends K, V1 extends V> CacheWriter<K1, V1> getCacheWriter() {
@SuppressWarnings("unchecked")
CacheWriter<K1, V1> castedWriter = (CacheWriter<K1, V1>) writer;
return (writer == null) ? CacheWriter.disabledWriter() : castedWriter;
}
/**
* Enables the accumulation of {@link CacheStats} during the operation of the cache. Without this
* {@link Cache#stats} will return zero for all statistics. Note that recording statistics
* requires bookkeeping to be performed with each operation, and thus imposes a performance
* penalty on cache operation.
*
* @return this builder instance
*/
@Nonnull
public Caffeine<K, V> recordStats() {
requireState(this.statsCounterSupplier == null, "Statistics recording was already set");
statsCounterSupplier = ENABLED_STATS_COUNTER_SUPPLIER;
return this;
}
/**
* Enables the accumulation of {@link CacheStats} during the operation of the cache. Without this
* {@link Cache#stats} will return zero for all statistics. Note that recording statistics
* requires bookkeeping to be performed with each operation, and thus imposes a performance
* penalty on cache operation. Any exception thrown by the supplied {@link StatsCounter} will be
* suppressed and logged.
*
* @param statsCounterSupplier a supplier instance that returns a new {@link StatsCounter}
* @return this builder instance
*/
@Nonnull
public Caffeine<K, V> recordStats(
@Nonnull Supplier<? extends StatsCounter> statsCounterSupplier) {
requireState(this.statsCounterSupplier == null, "Statistics recording was already set");
requireNonNull(statsCounterSupplier);
this.statsCounterSupplier = () -> StatsCounter.guardedStatsCounter(statsCounterSupplier.get());
return this;
}
boolean isRecordingStats() {
return (statsCounterSupplier != null);
}
@Nonnull
Supplier<? extends StatsCounter> getStatsCounterSupplier() {
return (statsCounterSupplier == null)
? StatsCounter::disabledStatsCounter
: statsCounterSupplier;
}
boolean isBounded() {
return (maximumSize != UNSET_INT)
|| (maximumWeight != UNSET_INT)
|| (expireAfterAccessNanos != UNSET_INT)
|| (expireAfterWriteNanos != UNSET_INT)
|| (expiry != null)
|| (keyStrength != null)
|| (valueStrength != null);
}
/**
* Builds a cache which does not automatically load values when keys are requested.
* <p>
* Consider {@link #build(CacheLoader)} instead, if it is feasible to implement a
* {@code CacheLoader}.
* <p>
* This method does not alter the state of this {@code Caffeine} instance, so it can be invoked
* again to create multiple independent caches.
*
* @param <K1> the key type of the cache
* @param <V1> the value type of the cache
* @return a cache having the requested features
*/
@Nonnull
public <K1 extends K, V1 extends V> Cache<K1, V1> build() {
requireWeightWithWeigher();
requireNonLoadingCache();
@SuppressWarnings("unchecked")
Caffeine<K1, V1> self = (Caffeine<K1, V1>) this;
return isBounded() || refreshes()
? new BoundedLocalCache.BoundedLocalManualCache<>(self)
: new UnboundedLocalCache.UnboundedLocalManualCache<>(self);
}
/**
* Builds a cache, which either returns an already-loaded value for a given key or atomically
* computes or retrieves it using the supplied {@code CacheLoader}. If another thread is currently
* loading the value for this key, simply waits for that thread to finish and returns its loaded
* value. Note that multiple threads can concurrently load values for distinct keys.
* <p>
* This method does not alter the state of this {@code Caffeine} instance, so it can be invoked
* again to create multiple independent caches.
*
* @param loader the cache loader used to obtain new values
* @param <K1> the key type of the loader
* @param <V1> the value type of the loader
* @return a cache having the requested features
* @throws NullPointerException if the specified cache loader is null
*/
@Nonnull
public <K1 extends K, V1 extends V> LoadingCache<K1, V1> build(
@Nonnull CacheLoader<? super K1, V1> loader) {
requireWeightWithWeigher();
@SuppressWarnings("unchecked")
Caffeine<K1, V1> self = (Caffeine<K1, V1>) this;
return isBounded() || refreshes()
? new BoundedLocalCache.BoundedLocalLoadingCache<>(self, loader)
: new UnboundedLocalCache.UnboundedLocalLoadingCache<>(self, loader);
}
/**
* Builds a cache, which either returns a {@link CompletableFuture} already loaded or currently
* computing the value for a given key, or atomically computes the value asynchronously through a
* supplied mapping function or the supplied {@code CacheLoader}. If the asynchronous computation
* fails or computes a {@code null} value then the entry will be automatically removed. Note that
* multiple threads can concurrently load values for distinct keys.
* <p>
* This method does not alter the state of this {@code Caffeine} instance, so it can be invoked
* again to create multiple independent caches.
*
* @param loader the cache loader used to obtain new values
* @param <K1> the key type of the loader
* @param <V1> the value type of the loader
* @return a cache having the requested features
* @throws IllegalStateException if the value strength is weak or soft
* @throws NullPointerException if the specified cache loader is null
*/
@Nonnull
public <K1 extends K, V1 extends V> AsyncLoadingCache<K1, V1> buildAsync(
@Nonnull CacheLoader<? super K1, V1> loader) {
return buildAsync((AsyncCacheLoader<? super K1, V1>) loader);
}
/**
* Builds a cache, which either returns a {@link CompletableFuture} already loaded or currently
* computing the value for a given key, or atomically computes the value asynchronously through a
* supplied mapping function or the supplied {@code AsyncCacheLoader}. If the asynchronous
* computation fails or computes a {@code null} value then the entry will be automatically
* removed. Note that multiple threads can concurrently load values for distinct keys.
* <p>
* This method does not alter the state of this {@code Caffeine} instance, so it can be invoked
* again to create multiple independent caches.
*
* @param loader the cache loader used to obtain new values
* @param <K1> the key type of the loader
* @param <V1> the value type of the loader
* @return a cache having the requested features
* @throws IllegalStateException if the value strength is weak or soft
* @throws NullPointerException if the specified cache loader is null
*/
@Nonnull
public <K1 extends K, V1 extends V> AsyncLoadingCache<K1, V1> buildAsync(
@Nonnull AsyncCacheLoader<? super K1, V1> loader) {
requireState(valueStrength == null);
requireState(writer == null);
requireWeightWithWeigher();
requireNonNull(loader);
@SuppressWarnings("unchecked")
Caffeine<K1, V1> self = (Caffeine<K1, V1>) this;
return isBounded() || refreshes()
? new BoundedLocalCache.BoundedLocalAsyncLoadingCache<>(self, loader)
: new UnboundedLocalCache.UnboundedLocalAsyncLoadingCache<>(self, loader);
}
void requireNonLoadingCache() {
requireState(refreshNanos == UNSET_INT, "refreshAfterWrite requires a LoadingCache");
}
void requireWeightWithWeigher() {
if (weigher == null) {
requireState(maximumWeight == UNSET_INT, "maximumWeight requires weigher");
} else if (strictParsing) {
requireState(maximumWeight != UNSET_INT, "weigher requires maximumWeight");
} else if (maximumWeight == UNSET_INT) {
logger.log(Level.WARNING, "ignoring weigher specified without maximumWeight");
}
}
/**
* Returns a string representation for this Caffeine instance. The exact form of the returned
* string is not specified.
*/
@Override
public String toString() {
StringBuilder s = new StringBuilder(64);
s.append(getClass().getSimpleName()).append('{');
int baseLength = s.length();
if (initialCapacity != UNSET_INT) {
s.append("initialCapacity=").append(initialCapacity).append(", ");
}
if (maximumSize != UNSET_INT) {
s.append("maximumSize=").append(maximumSize).append(", ");
}
if (maximumWeight != UNSET_INT) {
s.append("maximumWeight=").append(maximumWeight).append(", ");
}
if (expireAfterWriteNanos != UNSET_INT) {
s.append("expireAfterWrite=").append(expireAfterWriteNanos).append("ns, ");
}
if (expireAfterAccessNanos != UNSET_INT) {
s.append("expireAfterAccess=").append(expireAfterAccessNanos).append("ns, ");
}
if (expiry != null) {
s.append("expiry, ");
}
if (refreshNanos != UNSET_INT) {
s.append("refreshNanos=").append(refreshNanos).append("ns, ");
}
if (keyStrength != null) {
s.append("keyStrength=").append(keyStrength.toString().toLowerCase()).append(", ");
}
if (valueStrength != null) {
s.append("valueStrength=").append(valueStrength.toString().toLowerCase()).append(", ");
}
if (removalListener != null) {
s.append("removalListener, ");
}
if (writer != null) {
s.append("writer, ");
}
if (s.length() > baseLength) {
s.deleteCharAt(s.length() - 2);
}
return s.append('}').toString();
}
}