Module com.github.benmanes.caffeine
Package com.github.benmanes.caffeine.cache

Class Caffeine<K,V>

java.lang.Object
com.github.benmanes.caffeine.cache.Caffeine<K,V>
Type Parameters:
K - the most general key type this builder will be able to create caches for. This is normally Object unless it is constrained by using a method like #removalListener
V - the most general value type this builder will be able to create caches for. This is normally Object unless it is constrained by using a method like #removalListener
@NullMarked public final class Caffeine<K,V> extends Object
A builder of Cache, LoadingCache, AsyncCache, and AsyncLoadingCache instances having a combination of the following features:
  • automatic loading of entries into the cache, optionally asynchronously
  • size-based eviction when a maximum is exceeded based on frequency and recency
  • time-based expiration of entries, measured since last access or last write
  • asynchronously refresh when the first stale request for an entry occurs
  • keys automatically wrapped in weak references
  • values automatically wrapped in weak or soft references
  • writes propagated to an external resource
  • notification of evicted (or otherwise removed) entries
  • accumulation of cache access statistics

These features are all optional; caches can be created using all or none of them. By default, cache instances created by Caffeine will not perform any type of eviction.

Usage example: 


   LoadingCache<Key, Graph> graphs = Caffeine.newBuilder()
       .maximumSize(10_000)
       .expireAfterWrite(Duration.ofMinutes(10))
       .removalListener((Key key, Graph graph, RemovalCause cause) ->
           System.out.printf("Key %s was removed (%s)%n", key, cause))
       .build(key -> createExpensiveGraph(key));

The returned cache is implemented as a hash table with similar performance characteristics to ConcurrentHashMap. The asMap view (and its collection views) have weakly consistent iterators. 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 ConcurrentModificationException.

Note: By default, the returned cache uses equality comparisons (the equals method) to determine equality for keys or values. However, if weakKeys() was specified, the cache uses identity (==) comparisons instead for keys. Likewise, if weakValues() or softValues() was specified, the cache uses identity comparisons for values.

Entries are automatically evicted from the cache when any of maximumSize, maximumWeight, expireAfter, expireAfterWrite, expireAfterAccess, weakKeys, weakValues, or softValues are requested.

If maximumSize or maximumWeight is requested, entries may be evicted on each cache modification.

If expireAfter, expireAfterWrite, or expireAfterAccess is requested, then entries may be evicted on each cache modification, on occasional cache accesses, or on calls to Cache.cleanUp(). A scheduler(Scheduler) may be specified to provide prompt removal of expired entries rather than waiting until activity triggers the periodic maintenance. Expired entries may be counted by Cache.estimatedSize(), but will never be visible to read or write operations.

If weakKeys, weakValues, or 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 Cache.cleanUp(); such entries may be counted in Cache.estimatedSize(), but will never be visible to read or write operations.

Certain cache configurations will result in the accrual of periodic maintenance tasks that will be performed during write operations, or during occasional read operations in the absence of writes. The 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 maximumSize, maximumWeight, expireAfter, expireAfterWrite, expireAfterAccess, weakKeys, weakValues, or softValues perform periodic maintenance.

The caches produced by Caffeine are serializable, and the deserialized caches retain all the configuration properties of the original cache. Note that the serialized form does not include cache contents but only configuration.

  • Method Summary

    Modifier and Type
    Method
    Description
    <K1 extends K, V1 extends @Nullable V>
    Cache<K1,V1>
    build()
    Builds a cache which does not automatically load values when keys are requested unless a mapping function is provided.
    <K1 extends K, V1 extends @Nullable V>
    LoadingCache<K1,V1>
    build(CacheLoader<? super K1,V1> loader)
    Builds a cache, which either returns an already-loaded value for a given key or atomically computes or retrieves it using the supplied CacheLoader.
    <K1 extends K, V1 extends @Nullable V>
    AsyncCache<K1,V1>
    buildAsync()
    Builds a cache which does not automatically load values when keys are requested unless a mapping function is provided.
    <K1 extends K, V1 extends @Nullable V>
    AsyncLoadingCache<K1,V1>
    buildAsync(AsyncCacheLoader<? super K1,V1> loader)
    Builds a cache, which either returns a 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 AsyncCacheLoader.
    <K1 extends K, V1 extends @Nullable V>
    AsyncLoadingCache<K1,V1>
    buildAsync(CacheLoader<? super K1,V1> loader)
    Builds a cache, which either returns a 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 CacheLoader.
    <K1 extends K, V1 extends V>
    Caffeine<K1,V1>
    evictionListener(RemovalListener<? super K1,? super V1> evictionListener)
    Specifies a listener instance that caches should notify each time an entry is evicted.
    Caffeine<K,V>
    executor(Executor executor)
    Specifies the executor to use when running asynchronous tasks.
    <K1 extends K, V1 extends V>
    Caffeine<K1,V1>
    expireAfter(Expiry<? super K1,? super V1> expiry)
    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.
    Caffeine<K,V>
    expireAfterAccess(long duration, TimeUnit unit)
    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.
    Caffeine<K,V>
    expireAfterAccess(Duration duration)
    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 access.
    Caffeine<K,V>
    expireAfterWrite(long duration, TimeUnit unit)
    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.
    Caffeine<K,V>
    expireAfterWrite(Duration duration)
    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.
    static Caffeine<Object,Object>
    from(CaffeineSpec spec)
    Constructs a new Caffeine instance with the settings specified in spec.
    static Caffeine<Object,Object>
    from(String spec)
    Constructs a new Caffeine instance with the settings specified in spec.
    Caffeine<K,V>
    initialCapacity(int initialCapacity)
    Sets the minimum total size for the internal data structures.
    Caffeine<K,V>
    maximumSize(long maximumSize)
    Specifies the maximum number of entries the cache may contain.
    Caffeine<K,V>
    maximumWeight(long maximumWeight)
    Specifies the maximum weight of entries the cache may contain.
    static Caffeine<Object,Object>
    newBuilder()
    Constructs a new Caffeine instance with default settings, including strong keys, strong values, and no automatic eviction of any kind.
    Caffeine<K,V>
    recordStats()
    Enables the accumulation of CacheStats during the operation of the cache.
    Caffeine<K,V>
    recordStats(Supplier<? extends StatsCounter> statsCounterSupplier)
    Enables the accumulation of CacheStats during the operation of the cache.
    Caffeine<K,V>
    refreshAfterWrite(long duration, TimeUnit unit)
    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.
    Caffeine<K,V>
    refreshAfterWrite(Duration duration)
    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.
    <K1 extends K, V1 extends V>
    Caffeine<K1,V1>
    removalListener(RemovalListener<? super K1,? super V1> removalListener)
    Specifies a listener instance that caches should notify each time an entry is removed for any reason.
    Caffeine<K,V>
    scheduler(Scheduler scheduler)
    Specifies the scheduler to use when scheduling routine maintenance based on an expiration event.
    Caffeine<K,V>
    softValues()
    Specifies that each value (not key) stored in the cache should be wrapped in a SoftReference (by default, strong references are used).
    Caffeine<K,V>
    ticker(Ticker ticker)
    Specifies a nanosecond-precision time source for use in determining when entries should be expired or refreshed.
    String
    toString()
    Returns a string representation for this Caffeine instance.
    Caffeine<K,V>
    weakKeys()
    Specifies that each key (not value) stored in the cache should be wrapped in a WeakReference (by default, strong references are used).
    Caffeine<K,V>
    weakValues()
    Specifies that each value (not key) stored in the cache should be wrapped in a WeakReference (by default, strong references are used).
    <K1 extends K, V1 extends V>
    Caffeine<K1,V1>
    weigher(Weigher<? super K1,? super V1> weigher)
    Specifies the weigher to use in determining the weight of entries.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • newBuilder

      public static Caffeine<Object,Object> newBuilder()
      Constructs a new Caffeine instance with default settings, including strong keys, strong values, and no automatic eviction of any kind.

      Note that while this return type is Caffeine<Object, Object>, type parameters on the build() methods allow you to create a cache of any key and value type desired.

      Returns:
      a new instance with default settings

    • from

      public static Caffeine<Object,Object> from(CaffeineSpec spec)
      Constructs a new Caffeine instance with the settings specified in spec.
      Parameters:
      spec - the specification to build from
      Returns:
      a new instance with the specification's settings

    • from

      public static Caffeine<Object,Object> from(String spec)
      Constructs a new Caffeine instance with the settings specified in spec.
      Parameters:
      spec - a String in the format specified by CaffeineSpec
      Returns:
      a new instance with the specification's settings

    • initialCapacity

      @CanIgnoreReturnValue public Caffeine<K,V> initialCapacity(int initialCapacity)
      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.
      Parameters:
      initialCapacity - minimum total size for the internal data structures
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalArgumentException - if initialCapacity is negative
      IllegalStateException - if an initial capacity was already set

    • executor

      @CanIgnoreReturnValue public Caffeine<K,V> executor(Executor executor)
      Specifies the executor to use when running asynchronous tasks. The executor is delegated to when sending removal notifications, when asynchronous computations are performed by AsyncCache or LoadingCache.refresh(K) or refreshAfterWrite(java.time.Duration), or when performing periodic maintenance. By default, ForkJoinPool.commonPool() is used.

      The primary intent of this method is to facilitate testing of caches which have been configured with removalListener or utilize asynchronous computations. A test may instead prefer to configure the cache to execute tasks directly on the same thread.

      Beware that configuring a cache with an executor that discards tasks or never runs them may experience non-deterministic behavior.

      Parameters:
      executor - the executor to use for asynchronous execution
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      NullPointerException - if the specified executor is null

    • scheduler

      @CanIgnoreReturnValue public Caffeine<K,V> scheduler(Scheduler scheduler)
      Specifies the scheduler to use when scheduling routine maintenance based on an expiration event. This augments the periodic maintenance that occurs during normal cache operations to allow for the prompt removal of expired entries regardless of whether any cache activity is occurring at that time. By default, Scheduler.disabledScheduler() is used.

      The scheduling between expiration events is paced to exploit batching and to minimize executions in short succession. This minimum difference between the scheduled executions is implementation-specific, currently at ~1 second (2^30 ns). In addition, the provided scheduler may not offer real-time guarantees (including ScheduledThreadPoolExecutor). The scheduling is best-effort and does not make any hard guarantees of when an expired entry will be removed.

      Parameters:
      scheduler - the scheduler that submits a task to the executor(Executor) after a given delay
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      NullPointerException - if the specified scheduler is null

    • maximumSize

      @CanIgnoreReturnValue public Caffeine<K,V> maximumSize(long maximumSize)
      Specifies the maximum number of entries the cache may contain. Note that the cache may evict an entry before this limit is exceeded or temporarily exceed the threshold while evicting. 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.

      When maximumSize 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. As eviction is scheduled on the configured executor, tests may instead prefer to configure the cache to execute tasks directly on the same thread.

      This feature cannot be used in conjunction with maximumWeight.

      Parameters:
      maximumSize - the maximum size of the cache
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalArgumentException - if maximumSize is negative
      IllegalStateException - if a maximum size or weight was already set

    • maximumWeight

      @CanIgnoreReturnValue public Caffeine<K,V> maximumWeight(long maximumWeight)
      Specifies the maximum weight of entries the cache may contain. Weight is determined using the Weigher specified with weigher, and use of this method requires a corresponding call to weigher prior to calling build().

      Note that the cache may evict an entry before this limit is exceeded or temporarily exceed the threshold while evicting. 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.

      When maximumWeight 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. As eviction is scheduled on the configured executor, tests may instead prefer to configure the cache to execute tasks directly on the same thread.

      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.

      This feature cannot be used in conjunction with maximumSize.

      Parameters:
      maximumWeight - the maximum total weight of entries the cache may contain
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalArgumentException - if maximumWeight is negative
      IllegalStateException - if a maximum weight or size was already set

    • weigher

      @CanIgnoreReturnValue public <K1 extends K, V1 extends V> Caffeine<K1,V1> weigher(Weigher<? super K1,? super V1> weigher)
      Specifies the weigher to use in determining the weight of entries. Entry weight is taken into consideration by maximumWeight(long) when determining which entries to evict, and use of this method requires a corresponding call to maximumWeight(long) prior to calling 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.

      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).

      Important note: Instead of returning this as a Caffeine instance, this method returns 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 Caffeine type cannot do this. For best results, simply use the standard method-chaining idiom, as illustrated in the documentation at top, configuring a Caffeine and building your Cache all in a single statement.

      Warning: if you ignore the above advice, and use this Caffeine to build a cache whose key or value type is incompatible with the weigher, you will likely experience a ClassCastException at some undefined point in the future.

      Type Parameters:
      K1 - key type of the weigher
      V1 - value type of the weigher
      Parameters:
      weigher - the weigher to use in calculating the weight of cache entries
      Returns:
      the cache builder reference that should be used instead of this for any remaining configuration and cache building
      Throws:
      IllegalStateException - if a weigher was already set

    • weakKeys

      @CanIgnoreReturnValue public Caffeine<K,V> weakKeys()
      Specifies that each key (not value) stored in the cache should be wrapped in a WeakReference (by default, strong references are used).

      Warning: when this method is used, the resulting cache will use identity (==) comparison to determine equality of keys. Its Cache.asMap() view will therefore technically violate the Map specification (in the same way that IdentityHashMap does).

      Entries with keys that have been garbage collected may be counted in 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.

      This feature cannot be used in conjunction when evictionListener(RemovalListener) is combined with buildAsync().

      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalStateException - if the key strength was already set

    • weakValues

      @CanIgnoreReturnValue public Caffeine<K,V> weakValues()
      Specifies that each value (not key) stored in the cache should be wrapped in a WeakReference (by default, strong references are used).

      Weak values will be garbage collected once they are weakly reachable. This makes them a poor candidate for caching; consider softValues() instead.

      Note: when this method is used, the resulting cache will use identity (==) comparison to determine equality of values.

      Entries with values that have been garbage collected may be counted in 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.

      This feature cannot be used in conjunction with buildAsync().

      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalStateException - if the value strength was already set

    • softValues

      @CanIgnoreReturnValue public Caffeine<K,V> softValues()
      Specifies that each value (not key) stored in the cache should be wrapped in a SoftReference (by default, strong references are used). Softly-referenced objects will be garbage-collected in a globally least-recently-used manner, in response to memory demand.

      Warning: in most circumstances it is better to set a per-cache 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.

      Note: when this method is used, the resulting cache will use identity (==) comparison to determine equality of values.

      Entries with values that have been garbage collected may be counted in 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.

      This feature cannot be used in conjunction with buildAsync().

      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalStateException - if the value strength was already set

    • expireAfterWrite

      @CanIgnoreReturnValue public Caffeine<K,V> expireAfterWrite(Duration duration)
      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.

      Expired entries may be counted in 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. A scheduler(Scheduler) may be configured for a prompt removal of expired entries.

      Parameters:
      duration - the length of time after an entry is created or updated before it should be automatically removed
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalArgumentException - if duration is negative
      IllegalStateException - if the time to live or variable expiration was already set
      ArithmeticException - for durations greater than +/- approximately 292 years

    • expireAfterWrite

      @CanIgnoreReturnValue public Caffeine<K,V> expireAfterWrite(long duration, TimeUnit unit)
      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.

      Expired entries may be counted in 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. A scheduler(Scheduler) may be configured for a prompt removal of expired entries.

      If you can represent the duration as a Duration (which should be preferred when feasible), use expireAfterWrite(Duration) instead.

      Parameters:
      duration - the length of time after an entry is created or updated before it should be automatically removed
      unit - the unit that duration is expressed in
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalArgumentException - if duration is negative
      IllegalStateException - if the time to live or variable expiration was already set

    • expireAfterAccess

      @CanIgnoreReturnValue public Caffeine<K,V> expireAfterAccess(Duration duration)
      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 access. Access time is reset by all cache read and write operations (including Cache.asMap().get(Object) and Cache.asMap().put(K, V)), but not by operations on the collection-views of Cache.asMap().

      Expired entries may be counted in 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. A scheduler(Scheduler) may be configured for a prompt removal of expired entries.

      Parameters:
      duration - the length of time after an entry is last accessed before it should be automatically removed
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalArgumentException - if duration is negative
      IllegalStateException - if the time to idle or variable expiration was already set
      ArithmeticException - for durations greater than +/- approximately 292 years

    • expireAfterAccess

      @CanIgnoreReturnValue public Caffeine<K,V> expireAfterAccess(long duration, TimeUnit unit)
      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 Cache.asMap().get(Object) and Cache.asMap().put(K, V)), but not by operations on the collection-views of Cache.asMap().

      Expired entries may be counted in 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. A scheduler(Scheduler) may be configured for a prompt removal of expired entries.

      If you can represent the duration as a Duration (which should be preferred when feasible), use expireAfterAccess(Duration) instead.

      Parameters:
      duration - the length of time after an entry is last accessed before it should be automatically removed
      unit - the unit that duration is expressed in
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalArgumentException - if duration is negative
      IllegalStateException - if the time to idle or variable expiration was already set

    • expireAfter

      @CanIgnoreReturnValue public <K1 extends K, V1 extends V> Caffeine<K1,V1> expireAfter(Expiry<? super K1,? super V1> expiry)
      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 Cache.asMap().get(Object) and Cache.asMap().put(K, V)), but not by operations on the collection-views of Cache.asMap().

      Expired entries may be counted in 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. A scheduler(Scheduler) may be configured for a prompt removal of expired entries.

      Important note: after invoking this method, do not continue to use this cache builder reference; instead use the reference this method returns. 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 ClassCastException being thrown by a cache operation at some undefined point in the future.

      Type Parameters:
      K1 - key type of the expiry
      V1 - value type of the expiry
      Parameters:
      expiry - the expiry to use in calculating the expiration time of cache entries
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalStateException - if expiration was already set

    • refreshAfterWrite

      @CanIgnoreReturnValue public Caffeine<K,V> refreshAfterWrite(Duration duration)
      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 LoadingCache.refresh(K), and are performed by calling AsyncCacheLoader.asyncLoad(K, java.util.concurrent.Executor).

      Automatic refreshes are performed when the first stale request for an entry occurs. The request triggering the refresh will make a synchronous call to AsyncCacheLoader.asyncLoad(K, java.util.concurrent.Executor) to obtain a future of the new value. If the returned future is already complete, it is returned immediately. Otherwise, the old value is returned.

      Note: all exceptions thrown during refresh will be logged and then swallowed.

      Parameters:
      duration - the length of time after an entry is created that it should be considered stale, and thus eligible for refresh
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalArgumentException - if duration is zero or negative
      IllegalStateException - if the refresh interval was already set
      ArithmeticException - for durations greater than +/- approximately 292 years

    • refreshAfterWrite

      @CanIgnoreReturnValue public Caffeine<K,V> refreshAfterWrite(long duration, TimeUnit unit)
      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 LoadingCache.refresh(K), and are performed by calling AsyncCacheLoader.asyncLoad(K, java.util.concurrent.Executor).

      Automatic refreshes are performed when the first stale request for an entry occurs. The request triggering the refresh will make a synchronous call to AsyncCacheLoader.asyncLoad(K, java.util.concurrent.Executor) to obtain a future of the new value. If the returned future is already complete, it is returned immediately. Otherwise, the old value is returned.

      Note: all exceptions thrown during refresh will be logged and then swallowed.

      If you can represent the duration as a Duration (which should be preferred when feasible), use refreshAfterWrite(Duration) instead.

      Parameters:
      duration - the length of time after an entry is created that it should be considered stale, and thus eligible for refresh
      unit - the unit that duration is expressed in
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalArgumentException - if duration is zero or negative
      IllegalStateException - if the refresh interval was already set

    • ticker

      @CanIgnoreReturnValue public Caffeine<K,V> ticker(Ticker ticker)
      Specifies a nanosecond-precision time source for use in determining when entries should be expired or refreshed. By default, System.nanoTime() is used.

      The primary intent of this method is to facilitate testing of caches which have been configured with expireAfterWrite(java.time.Duration), expireAfterAccess(java.time.Duration), or refreshAfterWrite(java.time.Duration). Note that this ticker is not used when recording statistics.

      Parameters:
      ticker - a nanosecond-precision time source
      Returns:
      this Caffeine instance (for chaining)
      Throws:
      IllegalStateException - if a ticker was already set
      NullPointerException - if the specified ticker is null

    • evictionListener

      @CanIgnoreReturnValue public <K1 extends K, V1 extends V> Caffeine<K1,V1> evictionListener(RemovalListener<? super K1,? super V1> evictionListener)
      Specifies a listener instance that caches should notify each time an entry is evicted. The cache will invoke this listener during the atomic operation to remove the entry. In the case of expiration or reference collection, the entry may be pending removal and will be discarded as part of the routine maintenance described in the class documentation above. For a more prompt notification on expiration a scheduler(Scheduler) may be configured. A removalListener(RemovalListener) may be preferred when the listener should be invoked for any reason, be performed outside of the atomic operation to remove the entry, or be delegated to the configured executor(Executor).

      Important note: after invoking this method, do not continue to use this cache builder reference; instead use the reference this method returns. 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 ClassCastException being thrown by a cache operation at some undefined point in the future.

      Warning: any exception thrown by evictionListener will not be propagated to the Cache user, only logged via a System.Logger.

      This feature cannot be used in conjunction when weakKeys() is combined with buildAsync().

      Type Parameters:
      K1 - the key type of the listener
      V1 - the value type of the listener
      Parameters:
      evictionListener - a listener instance that caches should notify each time an entry is being automatically removed due to eviction
      Returns:
      the cache builder reference that should be used instead of this for any remaining configuration and cache building
      Throws:
      IllegalStateException - if a removal listener was already set
      NullPointerException - if the specified removal listener is null

    • removalListener

      @CanIgnoreReturnValue public <K1 extends K, V1 extends V> Caffeine<K1,V1> removalListener(RemovalListener<? super K1,? super V1> removalListener)
      Specifies a listener instance that caches should notify each time an entry is removed for any reason. The cache will invoke this listener on the configured executor(Executor) after the entry's removal operation has completed. In the case of expiration or reference collection, the entry may be pending removal and will be discarded as part of the routine maintenance described in the class documentation above. For a more prompt notification on expiration a scheduler(Scheduler) may be configured. An evictionListener(RemovalListener) may be preferred when the listener should be invoked as part of the atomic operation to remove the entry.

      Important note: after invoking this method, do not continue to use this cache builder reference; instead use the reference this method returns. 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 ClassCastException being thrown by a cache operation at some undefined point in the future.

      Warning: any exception thrown by removalListener will not be propagated to the Cache user, only logged via a System.Logger.

      Type Parameters:
      K1 - the key type of the listener
      V1 - the value type of the listener
      Parameters:
      removalListener - a listener instance that caches should notify each time an entry is removed
      Returns:
      the cache builder reference that should be used instead of this for any remaining configuration and cache building
      Throws:
      IllegalStateException - if a removal listener was already set
      NullPointerException - if the specified removal listener is null

    • recordStats

      @CanIgnoreReturnValue public Caffeine<K,V> recordStats()
      Enables the accumulation of CacheStats during the operation of the cache. Without this 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 operations.
      Returns:
      this Caffeine instance (for chaining)

    • recordStats

      @CanIgnoreReturnValue public Caffeine<K,V> recordStats(Supplier<? extends StatsCounter> statsCounterSupplier)
      Enables the accumulation of CacheStats during the operation of the cache. Without this 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 operations. Any exception thrown by the supplied StatsCounter will be suppressed and logged.
      Parameters:
      statsCounterSupplier - a supplier instance that returns a new StatsCounter
      Returns:
      this Caffeine instance (for chaining)

    • build

      public <K1 extends K, V1 extends @Nullable V> Cache<K1,V1> build()
      Builds a cache which does not automatically load values when keys are requested unless a mapping function is provided. Note that multiple threads can concurrently load values for distinct keys.

      Consider build(CacheLoader) instead, if it is feasible to implement a CacheLoader.

      This method does not alter the state of this Caffeine instance, so it can be invoked again to create multiple independent caches.

      Type Parameters:
      K1 - the key type of the cache
      V1 - the value type of the cache
      Returns:
      a cache having the requested features

    • build

      public <K1 extends K, V1 extends @Nullable V> LoadingCache<K1,V1> build(CacheLoader<? super K1,V1> loader)
      Builds a cache, which either returns an already-loaded value for a given key or atomically computes or retrieves it using the supplied 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.

      This method does not alter the state of this Caffeine instance, so it can be invoked again to create multiple independent caches.

      Type Parameters:
      K1 - the key type of the loader
      V1 - the value type of the loader
      Parameters:
      loader - the cache loader used to obtain new values
      Returns:
      a cache having the requested features

    • buildAsync

      public <K1 extends K, V1 extends @Nullable V> AsyncCache<K1,V1> buildAsync()
      Builds a cache which does not automatically load values when keys are requested unless a mapping function is provided. The returned CompletableFuture may be already loaded or currently computing the value for a given key. If the asynchronous computation fails or computes a null value then the entry will be automatically removed. Note that multiple threads can concurrently load values for distinct keys.

      Consider buildAsync(CacheLoader) or buildAsync(AsyncCacheLoader) instead, if it is feasible to implement an CacheLoader or AsyncCacheLoader.

      This method does not alter the state of this Caffeine instance, so it can be invoked again to create multiple independent caches.

      This construction cannot be used with weakValues(), softValues(), or when weakKeys() are combined with evictionListener(RemovalListener).

      Type Parameters:
      K1 - the key type of the cache
      V1 - the value type of the cache
      Returns:
      a cache having the requested features

    • buildAsync

      public <K1 extends K, V1 extends @Nullable V> AsyncLoadingCache<K1,V1> buildAsync(CacheLoader<? super K1,V1> loader)
      Builds a cache, which either returns a 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 CacheLoader. If the asynchronous computation fails or computes a null value then the entry will be automatically removed. Note that multiple threads can concurrently load values for distinct keys.

      This method does not alter the state of this Caffeine instance, so it can be invoked again to create multiple independent caches.

      This construction cannot be used with weakValues(), softValues(), or when weakKeys() are combined with evictionListener(RemovalListener).

      Type Parameters:
      K1 - the key type of the loader
      V1 - the value type of the loader
      Parameters:
      loader - the cache loader used to obtain new values
      Returns:
      a cache having the requested features

    • buildAsync

      public <K1 extends K, V1 extends @Nullable V> AsyncLoadingCache<K1,V1> buildAsync(AsyncCacheLoader<? super K1,V1> loader)
      Builds a cache, which either returns a 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 AsyncCacheLoader. If the asynchronous computation fails or computes a null value then the entry will be automatically removed. Note that multiple threads can concurrently load values for distinct keys.

      This method does not alter the state of this Caffeine instance, so it can be invoked again to create multiple independent caches.

      This construction cannot be used with weakValues(), softValues(), or when weakKeys() are combined with evictionListener(RemovalListener).

      Type Parameters:
      K1 - the key type of the loader
      V1 - the value type of the loader
      Parameters:
      loader - the cache loader used to obtain new values
      Returns:
      a cache having the requested features

    • toString

      public String toString()
      Returns a string representation for this Caffeine instance. The exact form of the returned string is not specified.
      Overrides:
      toString in class Object