public final class CacheBuilder<K,V>
extends java.lang.Object
| Modifier and Type | Method and Description |
|---|---|
<K1 extends K,V1 extends V> |
build() |
<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,
java.util.concurrent.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,
java.util.concurrent.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.
|
CacheBuilder<K,V> |
maximumSize(long size)
Specifies the maximum number of entries the cache may contain.
|
CacheBuilder<K,V> |
maximumWeight(long weight)
Specifies the maximum weight of entries the cache may contain.
|
static CacheBuilder<java.lang.Object,java.lang.Object> |
newBuilder()
Constructs a new
CacheBuilder instance with default settings, including strong keys,
strong values, and no automatic eviction of any kind. |
<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> |
ticker(Ticker ticker)
Specifies a nanosecond-precision time source for this cache.
|
java.lang.String |
toString()
Returns a string representation for this CacheBuilder instance.
|
<K1 extends K,V1 extends V> |
weigher(Weigher<? super K1,? super V1> weigher)
Specifies the weigher to use in determining the weight of entries.
|
@Nonnull public static CacheBuilder<java.lang.Object,java.lang.Object> newBuilder()
CacheBuilder instance with default settings, including strong keys,
strong values, and no automatic eviction of any kind.@Nonnull public 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.
java.lang.IllegalArgumentException - if concurrencyLevel is nonpositivejava.lang.IllegalStateException - if a concurrency level was already set@Nonnull public CacheBuilder<K,V> maximumSize(long size)
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.
This feature cannot be used in conjunction with maximumWeight.
size - the maximum size of the cachejava.lang.IllegalArgumentException - if size is negativejava.lang.IllegalStateException - if a maximum size or weight was already set@Nonnull public CacheBuilder<K,V> maximumWeight(long weight)
Weigher specified with weigher, and use of this method requires a
corresponding call to weigher prior to calling build(com.nytimes.android.external.cache.CacheLoader<? super K1, V1>).
Note that the cache may evict an entry before this limit is exceeded. 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 weight is zero, elements will be evicted immediately after being loaded into
cache. This can be useful in testing, or to disable caching temporarily without a code
change.
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.
weight - the maximum total weight of entries the cache may containjava.lang.IllegalArgumentException - if weight is negativejava.lang.IllegalStateException - if a maximum weight or size was already set@Nonnull public <K1 extends K,V1 extends V> CacheBuilder<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(com.nytimes.android.external.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 entriesjava.lang.IllegalArgumentException - if size is negativejava.lang.IllegalStateException - if a maximum size was already set@Nonnull public CacheBuilder<K,V> expireAfterWrite(long duration, @Nonnull java.util.concurrent.TimeUnit unit)
When duration is zero, this method hands off to
maximumSize(0), ignoring any otherwise-specificed 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 @link 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 injava.lang.IllegalArgumentException - if duration is negativejava.lang.IllegalStateException - if the time to live or time to idle was already set@Nonnull public CacheBuilder<K,V> expireAfterAccess(long duration, @Nonnull java.util.concurrent.TimeUnit unit)
Cache.asMap().get(Object) and Cache.asMap().put(K, V)), but not by operations
on the collection-views of @link Cache#asMap}.
When duration is zero, this method hands off to
maximumSize(0), ignoring any otherwise-specificed 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 @link 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 injava.lang.IllegalArgumentException - if duration is negativejava.lang.IllegalStateException - if the time to idle or time to live was already set@Nonnull public CacheBuilder<K,V> ticker(@Nonnull 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.
java.lang.IllegalStateException - if a ticker was already set@Nonnull public <K1 extends K,V1 extends V> CacheBuilder<K1,V1> removalListener(@Nonnull 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 buildingjava.lang.IllegalStateException - if a removal listener was already set@Nonnull public <K1 extends K,V1 extends V> 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 CacheBuilder instance, so it can be
invoked again to create multiple independent caches.
loader - the cache loader used to obtain new valuespublic java.lang.String toString()
toString in class java.lang.Object