com.nytimes.android.external.cache

Class CacheBuilder<K,V>

java.lang.Object

com.nytimes.android.external.cache.CacheBuilder<K,V>

public final class CacheBuilder<K,V>
extends java.lang.Object

Method Summary

Modifier and Type	Method and Description
<K1 extends K,V1 extends V> Cache<K1,V1>	build()
<K1 extends K,V1 extends 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.
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> CacheBuilder<K1,V1>	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> CacheBuilder<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 Detail

newBuilder

@Nonnull
public 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.

concurrencyLevel

@Nonnull
public CacheBuilder<K,V> concurrencyLevel(int concurrencyLevel)

Guides the allowed concurrency among update operations. Used as a hint for internal sizing. The table is internally partitioned to try to permit the indicated number of concurrent updates without contention. Because assignment of entries to these partitions is not necessarily uniform, the actual concurrency observed may vary. Ideally, you should choose a value to accommodate as many threads as will ever concurrently modify the table. Using a significantly higher value than you need can waste space and time, and a significantly lower value can lead to thread contention. But overestimates and underestimates within an order of magnitude do not usually have much noticeable impact. A value of one permits only one thread to modify the cache at a time, but since read operations and cache loading computations can proceed concurrently, this still yields higher concurrency than full synchronization.

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.

Throws:

java.lang.IllegalArgumentException - if concurrencyLevel is nonpositive

java.lang.IllegalStateException - if a concurrency level was already set

maximumSize

@Nonnull
public CacheBuilder<K,V> maximumSize(long size)

Specifies the maximum number of entries the cache may contain. 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 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.

Parameters:

size - the maximum size of the cache

Throws:

java.lang.IllegalArgumentException - if size is negative

java.lang.IllegalStateException - if a maximum size or weight was already set

maximumWeight

@Nonnull
public CacheBuilder<K,V> maximumWeight(long weight)

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

Parameters:

weight - the maximum total weight of entries the cache may contain

Throws:

java.lang.IllegalArgumentException - if weight is negative

java.lang.IllegalStateException - if a maximum weight or size was already set

Since:

11.0

weigher

@Nonnull
public <K1 extends K,V1 extends V> CacheBuilder<K1,V1> weigher(@Nonnull
                                                                        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(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.

Parameters:

weigher - the weigher to use in calculating the weight of cache entries

Throws:

java.lang.IllegalArgumentException - if size is negative

java.lang.IllegalStateException - if a maximum size was already set

Since:

11.0

expireAfterWrite

@Nonnull
public CacheBuilder<K,V> expireAfterWrite(long duration,
                                                   @Nonnull
                                                   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.

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.

Parameters:

duration - the length of time after an entry is created that it should be automatically removed

unit - the unit that duration is expressed in

Throws:

java.lang.IllegalArgumentException - if duration is negative

java.lang.IllegalStateException - if the time to live or time to idle was already set

expireAfterAccess

@Nonnull
public CacheBuilder<K,V> expireAfterAccess(long duration,
                                                    @Nonnull
                                                    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. 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 @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.

Parameters:

duration - the length of time after an entry is last accessed that it should be automatically removed

unit - the unit that duration is expressed in

Throws:

java.lang.IllegalArgumentException - if duration is negative

java.lang.IllegalStateException - if the time to idle or time to live was already set

ticker

@Nonnull
public CacheBuilder<K,V> ticker(@Nonnull
                                         Ticker ticker)

Specifies a nanosecond-precision time source for this cache. By default, System.nanoTime() is used.

The primary intent of this method is to facilitate testing of caches with a fake or mock time source.

Throws:

java.lang.IllegalStateException - if a ticker was already set

removalListener

@Nonnull
public <K1 extends K,V1 extends V> CacheBuilder<K1,V1> removalListener(@Nonnull
                                                                                RemovalListener<? super K1,? super V1> listener)

Specifies a listener instance that caches should notify each time an entry is removed for any reason. Each cache created by this builder will invoke this listener as part of the routine maintenance described in the class documentation above.

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.

Returns:

the cache builder reference that should be used instead of this for any remaining configuration and cache building

Throws:

java.lang.IllegalStateException - if a removal listener was already set

build

@Nonnull
public <K1 extends K,V1 extends V> LoadingCache<K1,V1> 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. 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.

Parameters:

loader - the cache loader used to obtain new values

Returns:

a cache having the requested features

build

@Nonnull
public <K1 extends K,V1 extends V> Cache<K1,V1> build()

toString

public java.lang.String toString()

Returns a string representation for this CacheBuilder instance. The exact form of the returned string is not specified.

Overrides:

toString in class java.lang.Object