K
- the base key type for all caches created by this builderV
- the base value type for all caches created by this builder@GwtCompatible(emulated=true) public final class CacheBuilder<K,V> extends Object
A builder of LoadingCache
and Cache
instances having any 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 CacheBuilder
will not perform any type of eviction.
Usage example:
LoadingCache<Key, Graph> graphs = CacheBuilder.newBuilder()
.maximumSize(10000)
.expireAfterWrite(10, TimeUnit.MINUTES)
.removalListener(MY_LISTENER)
.build(
new CacheLoader<Key, Graph>() {
public Graph load(Key key) throws AnyException {
return createExpensiveGraph(key);
}
});
Or equivalently,
// In real life this would come from a command-line flag or config file
String spec = "maximumSize=10000,expireAfterWrite=10m";
LoadingCache<Key, Graph> graphs = CacheBuilder.from(spec)
.removalListener(MY_LISTENER)
.build(
new CacheLoader<Key, Graph>() {
public Graph load(Key key) throws AnyException {
return createExpensiveGraph(key);
}
});
The returned cache is implemented as a hash table with similar performance characteristics to
ConcurrentHashMap
. It implements all optional operations of the LoadingCache
and
Cache
interfaces. 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, expireAfterWrite, expireAfterAccess, weakKeys, weakValues, or softValues are requested.
If maximumSize or maximumWeight is requested entries may be evicted on each cache modification.
If expireAfterWrite or expireAfterAccess is requested entries may be evicted on each cache modification, on occasional
cache accesses, or on calls to Cache.cleanUp()
. Expired entries may be counted by
Cache.size()
, 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.size()
, 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
removalListener, expireAfterWrite,
expireAfterAccess, weakKeys,
weakValues, or softValues perform periodic
maintenance.
The caches produced by CacheBuilder
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.
See the Guava User Guide article on caching for a higher-level explanation.
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.
|
<K1 extends K,V1 extends V> |
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 . |
CacheBuilder<K,V> |
concurrencyLevel(int concurrencyLevel)
Guides the allowed concurrency among update operations.
|
CacheBuilder<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
access.
|
CacheBuilder<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.
|
static CacheBuilder<Object,Object> |
from(CacheBuilderSpec spec)
Constructs a new
CacheBuilder instance with the settings specified in spec . |
static CacheBuilder<Object,Object> |
from(String spec)
Constructs a new
CacheBuilder instance with the settings specified in spec . |
CacheBuilder<K,V> |
initialCapacity(int initialCapacity)
Sets the minimum total size for the internal hash tables.
|
CacheBuilder<K,V> |
maximumSize(long maximumSize)
Specifies the maximum number of entries the cache may contain.
|
CacheBuilder<K,V> |
maximumWeight(long maximumWeight)
Specifies the maximum weight of entries the cache may contain.
|
static CacheBuilder<Object,Object> |
newBuilder()
Constructs a new
CacheBuilder instance with default settings, including strong keys,
strong values, and no automatic eviction of any kind. |
CacheBuilder<K,V> |
recordStats()
Enable the accumulation of
CacheStats during the operation of the cache. |
CacheBuilder<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.
|
<K1 extends K,V1 extends V> |
removalListener(RemovalListener<? super K1,? super V1> listener)
Specifies a listener instance that caches should notify each time an entry is removed for any
reason.
|
CacheBuilder<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). |
CacheBuilder<K,V> |
ticker(Ticker ticker)
Specifies a nanosecond-precision time source for this cache.
|
String |
toString()
Returns a string representation for this CacheBuilder instance.
|
CacheBuilder<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). |
CacheBuilder<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(Weigher<? super K1,? super V1> weigher)
Specifies the weigher to use in determining the weight of entries.
|
public static CacheBuilder<Object,Object> newBuilder()
CacheBuilder
instance with default settings, including strong keys,
strong values, and no automatic eviction of any kind.@GwtIncompatible public static CacheBuilder<Object,Object> from(CacheBuilderSpec spec)
CacheBuilder
instance with the settings specified in spec
.@GwtIncompatible public static CacheBuilder<Object,Object> from(String spec)
CacheBuilder
instance with the settings specified in spec
.
This is especially useful for command-line configuration of a CacheBuilder
.spec
- a String in the format specified by CacheBuilderSpec
public CacheBuilder<K,V> initialCapacity(int initialCapacity)
60
, and the concurrency level is 8
, then eight segments are created, each
having a hash table of size eight. Providing a large enough estimate at construction time
avoids the need for expensive resizing operations later, but setting this value unnecessarily
high wastes memory.CacheBuilder
instance (for chaining)IllegalArgumentException
- if initialCapacity
is negativeIllegalStateException
- if an initial capacity was already setpublic CacheBuilder<K,V> concurrencyLevel(int concurrencyLevel)
Defaults to 4. Note:The default may change in the future. If you care about this value, you should always choose it explicitly.
The current implementation uses the concurrency level to create a fixed number of hashtable
segments, each governed by its own write lock. The segment lock is taken once for each explicit
write, and twice for each cache loading computation (once prior to loading the new value, and
once after loading completes). Much internal cache management is performed at the segment
granularity. For example, access queues and write queues are kept per segment when they are
required by the selected eviction algorithm. As such, when writing unit tests it is not
uncommon to specify concurrencyLevel(1)
in order to achieve more deterministic eviction
behavior.
Note that future implementations may abandon segment locking in favor of more advanced concurrency controls.
CacheBuilder
instance (for chaining)IllegalArgumentException
- if concurrencyLevel
is nonpositiveIllegalStateException
- if a concurrency level was already setpublic CacheBuilder<K,V> maximumSize(long maximumSize)
Note that the cache may evict an entry before this limit is exceeded. For example, in
the current implementation, when concurrencyLevel
is greater than 1
, each
resulting segment inside the cache independently limits its own size to approximately
maximumSize / concurrencyLevel
.
When eviction is necessary, 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.
If maximumSize
is zero, elements will be evicted immediately after being loaded into
cache. This can be useful in testing, or to disable caching temporarily.
This feature cannot be used in conjunction with maximumWeight
.
maximumSize
- the maximum size of the cacheCacheBuilder
instance (for chaining)IllegalArgumentException
- if maximumSize
is negativeIllegalStateException
- if a maximum size or weight was already set@GwtIncompatible public CacheBuilder<K,V> maximumWeight(long maximumWeight)
Weigher
specified with weigher
, and use of this method requires a
corresponding call to weigher
prior to calling build(com.google.common.cache.CacheLoader<? super K1, V1>)
.
Note that the cache may evict an entry before this limit is exceeded. For example, in
the current implementation, when concurrencyLevel
is greater than 1
, each
resulting segment inside the cache independently limits its own weight to approximately
maximumWeight / concurrencyLevel
.
When eviction is necessary, 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.
If maximumWeight
is zero, elements will be evicted immediately after being loaded
into cache. This can be useful in testing, or to disable caching temporarily.
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 containCacheBuilder
instance (for chaining)IllegalArgumentException
- if maximumWeight
is negativeIllegalStateException
- if a maximum weight or size was already set@GwtIncompatible public <K1 extends K,V1 extends V> CacheBuilder<K1,V1> weigher(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(com.google.common.cache.CacheLoader<? super K1, V1>)
. Weights are measured and recorded when entries are inserted into 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 CacheBuilder
instance, this method returns CacheBuilder<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 CacheBuilder
type cannot do this. For best results,
simply use the standard method-chaining idiom, as illustrated in the documentation at top,
configuring a CacheBuilder
and building your Cache
all in a single statement.
Warning: if you ignore the above advice, and use this CacheBuilder
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.
weigher
- the weigher to use in calculating the weight of cache entriesCacheBuilder
instance (for chaining)IllegalArgumentException
- if size
is negativeIllegalStateException
- if a maximum size was already set@GwtIncompatible public CacheBuilder<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.
Entries with keys that have been garbage collected may be counted in Cache.size()
, 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.
CacheBuilder
instance (for chaining)IllegalStateException
- if the key strength was already set@GwtIncompatible public CacheBuilder<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.size()
,
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.
CacheBuilder
instance (for chaining)IllegalStateException
- if the value strength was already set@GwtIncompatible public CacheBuilder<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 well 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.size()
,
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.
CacheBuilder
instance (for chaining)IllegalStateException
- if the value strength was already setpublic CacheBuilder<K,V> expireAfterWrite(long duration, TimeUnit unit)
When duration
is zero, this method hands off to maximumSize
(0)
, ignoring any otherwise-specified maximum size or weight. This can be
useful in testing, or to disable caching temporarily without a code change.
Expired entries may be counted in Cache.size()
, 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
removedunit
- the unit that duration
is expressed inCacheBuilder
instance (for chaining)IllegalArgumentException
- if duration
is negativeIllegalStateException
- if the time to live or time to idle was already setpublic CacheBuilder<K,V> expireAfterAccess(long duration, TimeUnit unit)
Cache.asMap().get(Object)
and Cache.asMap().put(K, V)
), but not by operations
on the collection-views of Cache.asMap()
.
When duration
is zero, this method hands off to maximumSize
(0)
, ignoring any otherwise-specified maximum size or weight. This can be
useful in testing, or to disable caching temporarily without a code change.
Expired entries may be counted in Cache.size()
, 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 removedunit
- the unit that duration
is expressed inCacheBuilder
instance (for chaining)IllegalArgumentException
- if duration
is negativeIllegalStateException
- if the time to idle or time to live was already set@GwtIncompatible public CacheBuilder<K,V> refreshAfterWrite(long duration, TimeUnit unit)
LoadingCache.refresh(K)
, and are performed by calling
CacheLoader.reload(K, V)
.
As the default implementation of CacheLoader.reload(K, V)
is synchronous, it is
recommended that users of this method override CacheLoader.reload(K, V)
with an asynchronous
implementation; otherwise refreshes will be performed during unrelated cache read and write
operations.
Currently automatic refreshes are performed when the first stale request for an entry
occurs. The request triggering refresh will make a blocking call to CacheLoader.reload(K, V)
and immediately return the new value if the returned future is complete, and the old value
otherwise.
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 refreshunit
- the unit that duration
is expressed inCacheBuilder
instance (for chaining)IllegalArgumentException
- if duration
is negativeIllegalStateException
- if the refresh interval was already setpublic CacheBuilder<K,V> ticker(Ticker ticker)
System.nanoTime()
is used.
The primary intent of this method is to facilitate testing of caches with a fake or mock time source.
CacheBuilder
instance (for chaining)IllegalStateException
- if a ticker was already set@CheckReturnValue public <K1 extends K,V1 extends V> CacheBuilder<K1,V1> removalListener(RemovalListener<? super K1,? super V1> listener)
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
.
this
for any
remaining configuration and cache buildingIllegalStateException
- if a removal listener was already setpublic CacheBuilder<K,V> recordStats()
CacheStats
during the operation of the cache. Without this
Cache.stats()
will return zero for all statistics. Note that recording stats requires
bookkeeping to be performed with each operation, and thus imposes a performance penalty on
cache operation.CacheBuilder
instance (for chaining)public <K1 extends K,V1 extends V> LoadingCache<K1,V1> build(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 CacheBuilder
instance, so it can be
invoked again to create multiple independent caches.
loader
- the cache loader used to obtain new valuespublic <K1 extends K,V1 extends V> 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 CacheBuilder
instance, so it can be
invoked again to create multiple independent caches.
Copyright © 2010-2017. All Rights Reserved.