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
public final class Caffeine<K,V> extends Object
Cache
, LoadingCache
, AsyncCache
, and
AsyncLoadingCache
instances having a combination of the following features:
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 which
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.
Modifier and Type | Method and Description |
---|---|
<K1 extends K,V1 extends V> |
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 V> |
build(@NonNull 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 V> |
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 V> |
buildAsync(@NonNull 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 V> |
buildAsync(@NonNull 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 . |
@NonNull Caffeine<K,V> |
executor(@NonNull Executor executor)
Specifies the executor to use when running asynchronous tasks.
|
<K1 extends K,V1 extends V> |
expireAfter(@NonNull 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.
|
@NonNull Caffeine<K,V> |
expireAfterAccess(@NonNull 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.
|
@NonNull Caffeine<K,V> |
expireAfterAccess(@NonNegative long duration,
@NonNull 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.
|
@NonNull Caffeine<K,V> |
expireAfterWrite(@NonNull 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.
|
@NonNull Caffeine<K,V> |
expireAfterWrite(@NonNegative long duration,
@NonNull 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.
|
static @NonNull Caffeine<Object,Object> |
from(CaffeineSpec spec)
Constructs a new
Caffeine instance with the settings specified in spec . |
static @NonNull Caffeine<Object,Object> |
from(String spec)
Constructs a new
Caffeine instance with the settings specified in spec . |
@NonNull Caffeine<K,V> |
initialCapacity(@NonNegative int initialCapacity)
Sets the minimum total size for the internal data structures.
|
@NonNull Caffeine<K,V> |
maximumSize(@NonNegative long maximumSize)
Specifies the maximum number of entries the cache may contain.
|
@NonNull Caffeine<K,V> |
maximumWeight(@NonNegative long maximumWeight)
Specifies the maximum weight of entries the cache may contain.
|
static @NonNull Caffeine<Object,Object> |
newBuilder()
Constructs a new
Caffeine instance with default settings, including strong keys, strong
values, and no automatic eviction of any kind. |
@NonNull Caffeine<K,V> |
recordStats()
Enables the accumulation of
CacheStats during the operation of the cache. |
@NonNull Caffeine<K,V> |
recordStats(@NonNull Supplier<? extends StatsCounter> statsCounterSupplier)
Enables the accumulation of
CacheStats during the operation of the cache. |
@NonNull Caffeine<K,V> |
refreshAfterWrite(@NonNull 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.
|
@NonNull Caffeine<K,V> |
refreshAfterWrite(@NonNegative long duration,
@NonNull 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.
|
<K1 extends K,V1 extends V> |
removalListener(@NonNull RemovalListener<? super K1,? super V1> removalListener)
Specifies a listener instance that caches should notify each time an entry is removed for any
reason.
|
@NonNull Caffeine<K,V> |
scheduler(@NonNull Scheduler scheduler)
Specifies the scheduler to use when scheduling routine maintenance based on an expiration
event.
|
@NonNull 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). |
@NonNull Caffeine<K,V> |
ticker(@NonNull 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.
|
@NonNull 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). |
@NonNull 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> |
weigher(@NonNull Weigher<? super K1,? super V1> weigher)
Specifies the weigher to use in determining the weight of entries.
|
<K1 extends K,V1 extends V> |
writer(@NonNull CacheWriter<? super K1,? super V1> writer)
Specifies a writer instance that caches should notify each time an entry is explicitly created
or modified, or removed for any reason.
|
public static @NonNull Caffeine<Object,Object> newBuilder()
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.
public static @NonNull Caffeine<Object,Object> from(CaffeineSpec spec)
Caffeine
instance with the settings specified in spec
.spec
- the specification to build frompublic static @NonNull Caffeine<Object,Object> from(String spec)
Caffeine
instance with the settings specified in spec
.spec
- a String in the format specified by CaffeineSpec
public @NonNull Caffeine<K,V> initialCapacity(@NonNegative int initialCapacity)
initialCapacity
- minimum total size for the internal data structuresCaffeine
instance (for chaining)IllegalArgumentException
- if initialCapacity
is negativeIllegalStateException
- if an initial capacity was already setpublic @NonNull Caffeine<K,V> executor(@NonNull Executor executor)
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 throws RejectedExecutionException
may experience non-deterministic behavior.
executor
- the executor to use for asynchronous executionCaffeine
instance (for chaining)NullPointerException
- if the specified executor is nullpublic @NonNull Caffeine<K,V> scheduler(@NonNull Scheduler scheduler)
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.
Note for Java 9 and later: consider using Scheduler.systemScheduler()
to
leverage the dedicated, system-wide scheduling thread.
scheduler
- the scheduler that submits a task to the executor(Executor)
after a
given delayCaffeine
instance (for chaining)NullPointerException
- if the specified scheduler is nullpublic @NonNull Caffeine<K,V> maximumSize(@NonNegative long maximumSize)
When 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.
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
.
maximumSize
- the maximum size of the cacheCaffeine
instance (for chaining)IllegalArgumentException
- if size
is negativeIllegalStateException
- if a maximum size or weight was already setpublic @NonNull Caffeine<K,V> maximumWeight(@NonNegative long maximumWeight)
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
.
maximumWeight
- the maximum total weight of entries the cache may containCaffeine
instance (for chaining)IllegalArgumentException
- if maximumWeight
is negativeIllegalStateException
- if a maximum weight or size was already setpublic <K1 extends K,V1 extends V> @NonNull Caffeine<K1,V1> weigher(@NonNull Weigher<? super K1,? super V1> weigher)
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.
K1
- key type of the weigherV1
- value type of the weigherweigher
- the weigher to use in calculating the weight of cache entriesthis
for any
remaining configuration and cache buildingIllegalStateException
- if a weigher was already setpublic @NonNull Caffeine<K,V> weakKeys()
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 with writer
.
Caffeine
instance (for chaining)IllegalStateException
- if the key strength was already set or the writer was setpublic @NonNull Caffeine<K,V> weakValues()
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()
.
Caffeine
instance (for chaining)IllegalStateException
- if the value strength was already setpublic @NonNull Caffeine<K,V> softValues()
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()
.
Caffeine
instance (for chaining)IllegalStateException
- if the value strength was already setpublic @NonNull Caffeine<K,V> expireAfterWrite(@NonNull Duration duration)
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.
duration
- the length of time after an entry is created that it should be automatically
removedCaffeine
instance (for chaining)IllegalArgumentException
- if duration
is negativeIllegalStateException
- if the time to live or time to idle was already setArithmeticException
- for durations greater than +/- approximately 292 yearspublic @NonNull Caffeine<K,V> expireAfterWrite(@NonNegative long duration, @NonNull TimeUnit unit)
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.
If you can represent the duration as a Duration
(which should be preferred
when feasible), use expireAfterWrite(Duration)
instead.
duration
- the length of time after an entry is created that it should be automatically
removedunit
- the unit that duration
is expressed inCaffeine
instance (for chaining)IllegalArgumentException
- if duration
is negativeIllegalStateException
- if the time to live or variable expiration was already setpublic @NonNull Caffeine<K,V> expireAfterAccess(@NonNull Duration duration)
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.
duration
- the length of time after an entry is last accessed that it should be
automatically removedCaffeine
instance (for chaining)IllegalArgumentException
- if duration
is negativeIllegalStateException
- if the time to idle or time to live was already setArithmeticException
- for durations greater than +/- approximately 292 yearspublic @NonNull Caffeine<K,V> expireAfterAccess(@NonNegative long duration, @NonNull TimeUnit unit)
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.
If you can represent the duration as a Duration
(which should be preferred
when feasible), use expireAfterAccess(Duration)
instead.
duration
- the length of time after an entry is last accessed that it should be
automatically removedunit
- the unit that duration
is expressed inCaffeine
instance (for chaining)IllegalArgumentException
- if duration
is negativeIllegalStateException
- if the time to idle or variable expiration was already setpublic <K1 extends K,V1 extends V> @NonNull Caffeine<K1,V1> expireAfter(@NonNull Expiry<? super K1,? super V1> expiry)
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.
K1
- key type of the weigherV1
- value type of the weigherexpiry
- the expiry to use in calculating the expiration time of cache entriesCaffeine
instance (for chaining)IllegalStateException
- if expiration was already setpublic @NonNull Caffeine<K,V> refreshAfterWrite(@NonNull Duration duration)
LoadingCache.refresh(K)
, and are performed by calling CacheLoader.reload(K, V)
.
Automatic refreshes are performed when the first stale request for an entry occurs. The request
triggering refresh will make an asynchronous call to CacheLoader.reload(K, V)
and immediately
return the old value.
Note: all exceptions thrown during refresh will be logged and then swallowed.
duration
- the length of time after an entry is created that it should be considered
stale, and thus eligible for refreshCaffeine
instance (for chaining)IllegalArgumentException
- if duration
is zero or negativeIllegalStateException
- if the refresh interval was already setArithmeticException
- for durations greater than +/- approximately 292 yearspublic @NonNull Caffeine<K,V> refreshAfterWrite(@NonNegative long duration, @NonNull TimeUnit unit)
LoadingCache.refresh(K)
, and are performed by calling
CacheLoader.reload(K, V)
.
Automatic refreshes are performed when the first stale request for an entry occurs. The request
triggering refresh will make an asynchronous call to CacheLoader.reload(K, V)
and immediately
return the old value.
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.
duration
- the length of time after an entry is created that it should be considered
stale, and thus eligible for refreshunit
- the unit that duration
is expressed inCaffeine
instance (for chaining)IllegalArgumentException
- if duration
is zero or negativeIllegalStateException
- if the refresh interval was already setpublic @NonNull Caffeine<K,V> ticker(@NonNull Ticker ticker)
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)
.
ticker
- a nanosecond-precision time sourceCaffeine
instance (for chaining)IllegalStateException
- if a ticker was already setNullPointerException
- if the specified ticker is nullpublic <K1 extends K,V1 extends V> @NonNull Caffeine<K1,V1> removalListener(@NonNull RemovalListener<? super K1,? super V1> removalListener)
Warning: 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 listener
will not be propagated to the
Cache
user, only logged via a Logger
.
K1
- the key type of the listenerV1
- the value type of the listenerremovalListener
- a listener instance that caches should notify each time an entry is
removedthis
for any
remaining configuration and cache buildingIllegalStateException
- if a removal listener was already setNullPointerException
- if the specified removal listener is nullpublic <K1 extends K,V1 extends V> @NonNull Caffeine<K1,V1> writer(@NonNull CacheWriter<? super K1,? super V1> writer)
Warning: 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 writer
will be propagated to the Cache
user.
This feature cannot be used in conjunction with weakKeys()
or buildAsync()
.
K1
- the key type of the writerV1
- the value type of the writerwriter
- a writer instance that caches should notify each time an entry is explicitly
created or modified, or removed for any reasonthis
for any
remaining configuration and cache buildingIllegalStateException
- if a writer was already set or if the key strength is weakNullPointerException
- if the specified writer is nullpublic @NonNull Caffeine<K,V> recordStats()
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 operation.Caffeine
instance (for chaining)public @NonNull Caffeine<K,V> recordStats(@NonNull Supplier<? extends StatsCounter> statsCounterSupplier)
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 operation. Any exception thrown by the supplied StatsCounter
will be
suppressed and logged.statsCounterSupplier
- a supplier instance that returns a new StatsCounter
Caffeine
instance (for chaining)public <K1 extends K,V1 extends V> @NonNull Cache<K1,V1> build()
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.
K1
- the key type of the cacheV1
- the value type of the cachepublic <K1 extends K,V1 extends V> @NonNull LoadingCache<K1,V1> build(@NonNull CacheLoader<? super K1,V1> loader)
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.
K1
- the key type of the loaderV1
- the value type of the loaderloader
- the cache loader used to obtain new valuespublic <K1 extends K,V1 extends V> @NonNull AsyncCache<K1,V1> buildAsync()
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
writer(CacheWriter)
.
K1
- the key type of the cacheV1
- the value type of the cachepublic <K1 extends K,V1 extends V> @NonNull AsyncLoadingCache<K1,V1> buildAsync(@NonNull CacheLoader<? super K1,V1> loader)
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
writer(CacheWriter)
.
K1
- the key type of the loaderV1
- the value type of the loaderloader
- the cache loader used to obtain new valuespublic <K1 extends K,V1 extends V> @NonNull AsyncLoadingCache<K1,V1> buildAsync(@NonNull AsyncCacheLoader<? super K1,V1> loader)
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
writer(CacheWriter)
.
K1
- the key type of the loaderV1
- the value type of the loaderloader
- the cache loader used to obtain new values