com.comphenix.protocol.utility

Class SafeCacheBuilder<K,V>

java.lang.Object

com.comphenix.protocol.utility.SafeCacheBuilder<K,V>

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

Represents a Guava CacheBuilder that is compatible with both Guava 10 and 13.

Author:

Kristian

Method Summary

Methods

Modifier and Type	Method and Description
<K1 extends K,V1 extends V> java.util.concurrent.ConcurrentMap<K1,V1>	build(com.google.common.cache.CacheLoader<? super K1,V1> loader) Returns the cache wrapped as a ConcurrentMap.
SafeCacheBuilder<K,V>	concurrencyLevel(int concurrencyLevel) Guides the allowed concurrency among update operations.
SafeCacheBuilder<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, or last access.
SafeCacheBuilder<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.
SafeCacheBuilder<K,V>	initialCapacity(int initialCapacity) Sets the minimum total size for the internal hash tables.
SafeCacheBuilder<K,V>	maximumSize(int size) Specifies the maximum number of entries the cache may contain.
static <K,V> SafeCacheBuilder<K,V>	newBuilder() Construct a new safe cache builder.
<K1 extends K,V1 extends V> SafeCacheBuilder<K1,V1>	removalListener(com.google.common.cache.RemovalListener<? super K1,? super V1> listener) Specifies a listener instance, which all caches built using this CacheBuilder will notify each time an entry is removed from the cache by any means.
SafeCacheBuilder<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).
SafeCacheBuilder<K,V>	ticker(com.google.common.base.Ticker ticker) Specifies a nanosecond-precision time source for use in determining when entries should be expired.
SafeCacheBuilder<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).
SafeCacheBuilder<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).

Methods inherited from class java.lang.Object

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

Method Detail

newBuilder

public static <K,V> SafeCacheBuilder<K,V> newBuilder()

Construct a new safe cache builder.

Returns:

A new cache builder.

concurrencyLevel

public SafeCacheBuilder<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 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.

Throws:

java.lang.IllegalArgumentException - if concurrencyLevel is nonpositive

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

expireAfterAccess

public SafeCacheBuilder<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, or last access. Access time is reset by Cache.get() and Cache.getUnchecked(), but not by operations on the view returned by Cache.asMap().

When duration is zero, elements will be evicted immediately after being loaded into the cache. This has the same effect as invoking maximumSize(0). It can be useful in testing, or to disable caching temporarily without a code change.

Expired entries may be counted by Cache.size(), but will never be visible to read or write operations. Expired entries are currently cleaned up during write operations, or during occasional read operations in the absense of writes; though this behavior may change in the future.

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

expireAfterWrite

public SafeCacheBuilder<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.

When duration is zero, elements will be evicted immediately after being loaded into the cache. This has the same effect as invoking maximumSize(0). It can be useful in testing, or to disable caching temporarily without a code change.

Expired entries may be counted by Cache.size(), but will never be visible to read or write operations. Expired entries are currently cleaned up during write operations, or during occasional read operations in the absense of writes; though this behavior may change in the future.

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

initialCapacity

public SafeCacheBuilder<K,V> initialCapacity(int initialCapacity)

Sets the minimum total size for the internal hash tables. For example, if the initial capacity is 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.

Throws:

java.lang.IllegalArgumentException - if initialCapacity is negative

java.lang.IllegalStateException - if an initial capacity was already set

maximumSize

public SafeCacheBuilder<K,V> maximumSize(int 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 has the same effect as invoking expireAfterWrite(0, unit) or expireAfterAccess(0, unit). It can be useful in testing, or to disable caching temporarily without a code change.

Parameters:

size - the maximum size of the cache

Throws:

java.lang.IllegalArgumentException - if size is negative

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

removalListener

public <K1 extends K,V1 extends V> SafeCacheBuilder<K1,V1> removalListener(com.google.common.cache.RemovalListener<? super K1,? super V1> listener)

Specifies a listener instance, which all caches built using this CacheBuilder will notify each time an entry is removed from the cache by any means.

Each cache built by this CacheBuilder after this method is called invokes the supplied listener after removing an element for any reason (see removal causes in RemovalCause). It will invoke the listener during invocations of any of that cache's public methods (even read-only methods).

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 listener 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 listener, you will likely experience a ClassCastException at some undefined point in the future.

Throws:

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

ticker

public SafeCacheBuilder<K,V> ticker(com.google.common.base.Ticker ticker)

Specifies a nanosecond-precision time source for use in determining when entries should be expired. By default, System.nanoTime() is used.

The primary intent of this method is to facilitate testing of caches which have been configured with expireAfterWrite(long, java.util.concurrent.TimeUnit) or expireAfterAccess(long, java.util.concurrent.TimeUnit).

Throws:

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

softValues

public SafeCacheBuilder<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 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.

Throws:

java.lang.IllegalStateException - if the value strength was already set

weakKeys

public SafeCacheBuilder<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.

Throws:

java.lang.IllegalStateException - if the key strength was already set

weakValues

public SafeCacheBuilder<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.

Throws:

java.lang.IllegalStateException - if the value strength was already set

build

public <K1 extends K,V1 extends V> java.util.concurrent.ConcurrentMap<K1,V1> build(com.google.common.cache.CacheLoader<? super K1,V1> loader)

Returns the cache wrapped as a ConcurrentMap. <> We can't return the direct Cache instance as it changed in Guava 13.

Returns:

The cache as a map.