Cache (triava 2.0.1 API)

java.lang.Object
- com.trivago.triava.tcache.Cache<K,V>

Type Parameters:

K - The Key type

V - The Value type

All Implemented Interfaces:

ActionContext<K,V>, Thread.UncaughtExceptionHandler

Direct Known Subclasses:

CacheLimit
```
public class Cache<K,V>
extends Object
implements Thread.UncaughtExceptionHandler, ActionContext<K,V>
```
A Cache that supports expiration based on expiration time and idle time. The Cache can be of unbounded or bounded size. In the latter case, eviction is done using the selected strategy, for example LFU, LRU, Clock or an own implemented custom eviction strategy (key and value type aware). You can retrieve either instance by using a Builder:
```
 // Build native TCache instance
 Builder<String, Integer> builder = TCacheFactory.standardFactory().builder();
 builder.setXYZ(value);
 Cache<String, Integer> cache = builder.build();
 javax.cache.Cache<String, Integer> jsr107cache = tcache.jsr107cache();
 
```
The last line above is optional, to get a JSR107 compliant Cache instance. Alternatively that could also be created via the JSR107 API:
```
 // Build JSR107 Cache instance
 CachingProvider cachingProvider = Caching.getCachingProvider();
 CacheManager cacheManager = cachingProvider.getCacheManager();
 MutableConfiguration<String, Integer> config = new MutableConfiguration<>()
   .setXYZ(value); // Configure
 javax.cache.Cache<String, Integer> cache = cacheManager.createCache("simpleCache", config);  // Build
 
```
Implementation note: This Cache class is built for maximum throughput and scalability, by executing CPU intensive tasks like evictions in separate Threads. The basic limitations are those of the underlying ConcurrentMap implementation, as no further data structures are maintained. This is also true for the subclasses that allow evictions.
Since:

2009-06-10

Author:

Christian Esken

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

class Cache.CleanupThread
Thread that removes expired entries.

Nested Classes
Modifier and Type	Class and Description
`class`	`Cache.CleanupThread` Thread that removes expired entries.

Field Summary

Fields
Modifier and Type	Field and Description
`protected JamPolicy`	`jamPolicy`
`protected javax.cache.integration.CacheLoader<K,V>`	`loader`
`protected ConcurrentMap<K,AccessTimeObjectHolder<V>>`	`objects`

Constructor Summary

Constructors
Constructor and Description

Cache(TCacheFactory factory, Builder<K,V> builder)
Construct a Cache, using the given configuration from the Builder.

Constructors
Constructor and Description
`Cache(TCacheFactory factory, Builder<K,V> builder)` Construct a Cache, using the given configuration from the Builder.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected TimeSource`	`activateTimeSource()` Returns the TimeSource for this Cache.
`javax.cache.integration.CacheWriter<K,V>`	`cacheWriter()`
`void`	`clear()` Removes all entries from the Cache without notifying Listeners
`void`	`close()` Closes the cache and removes it from the associated CacheManager.
`protected String`	`configToString()`
`TriavaCacheConfiguration<K,V,? extends Builder<K,V>>`	`configuration()`
`boolean`	`containsKey(K key)` Returns true if this Cache contains a mapping for the specified key.
`void`	`enableManagement(boolean enable)`
`void`	`enableStatistics(boolean enable)` Enables or disables statistics.
`protected boolean`	`ensureFreeCapacity()` Returns whether there is capacity for at least one more element.
`protected int`	`evictionExtraSpace(Builder<K,V> builder)` Returns a size factor for the map for the specific eviction strategy of this Cache.
`void`	`expireUntil(K key, int maxDelay, TimeUnit timeUnit)` Schedule the entry for the given key for expiration.
`protected TCacheStatisticsInterface`	`fillCacheStatistics(TCacheStatisticsInterface cacheStatistic)` Fills the given cache statistics object.
`protected AccessTimeObjectHolder<V>`	`gatedHolder(AccessTimeObjectHolder<V> holder)`
`V`	`get(K key)` Gets cached object for the given key, or null if this Cache contains no mapping for the key.
`V`	`getAndPut(K key, V value)` Add an object to the cache under the given key, using the default idle time and default cache time.
`V`	`getAndReplace(K key, V value)` Replace the entry stored by key with the given value.
`float`	`getCacheHitrate()` Returns the Cache hit rate.
`String`	`id()`
`boolean`	`isClosed()`
`boolean`	`isManagementEnabled()`
`boolean`	`isStatisticsEnabled()`
`TCacheHolderIterator<K,V>`	`iterator()` Returns an Iterator which can be used to traverse all entries of the Cache.
`TCacheHolderIterator<K,V>`	`iteratorWithTouch()` Returns an Iterator which can be used to traverse all entries of the Cache.
`boolean`	`joinSimple(Thread thread, long millis, int nanos)` Waits at most millis milliseconds plus nanos nanoseconds for the given thread to die.
`TCacheJSR107<K,V>`	`jsr107cache()` Returns a JSR107 compliant view on this Cache.
`Collection<K>`	`keySet()` Returns a thread-safe unmodifiable collection of the keys.
`ListenerCollection<K,V>`	`listeners()`
`void`	`put(K key, V value)` Add an object to the cache under the given key, using the default idle time and default cache time.
`void`	`put(K key, V value, int idleTime, int cacheTime, TimeUnit timeUnit)` Add an object to the cache under the given key with the given idle and cache times.
`V`	`putIfAbsent(K key, V value)` The same like `putIfAbsent(Object, Object, int, int, TimeUnit)`, but uses the default idle and cache times.
`V`	`putIfAbsent(K key, V value, int idleTime, int cacheTime, TimeUnit timeUnit)` The same like `put(Object, Object, int, int, TimeUnit)`, but uses `ConcurrentMap.putIfAbsent(Object, Object)` to actually write the data in the backing ConcurrentMap.
`protected AccessTimeObjectHolder<V>`	`putToMap(K key, V data, long idleTime, long cacheTime, boolean putIfAbsent, boolean returnEffectiveHolder)` Puts the value wrapped in a AccessTimeObjectHolder in the map and returns it.
`V`	`remove(K key)` Removes the mapping for the given key, and returns the value that was stored for it.
`boolean`	`remove(K key, V value)` Removes the object with given key, if stored in the Cache.
`protected V`	`removeAndRelease(K key)` Removes the mapping for the given key, and releases the associated holder.
`ChangeStatus`	`replace(K key, V oldValue, V newValue)`
`CacheSizeInfo`	`reportSize(ObjectSizeCalculatorInterface objectSizeCalculator)` Measures the number of elements and the size of this Cache in bytes and logs it.
`static void`	`setLogger(TriavaLogger logger)` Sets the logger that will be used for all Cache instances.
`int`	`size()`
`TCacheStatistics`	`statistics()`
`StatisticsCalculator`	`statisticsCalculator()`
`protected String`	`stopAndClear(long millis)`
`String`	`toString()`
`void`	`uncaughtException(Thread thread, Throwable throwable)` This is called, if the CleanupThread goes down on an unexpected (uncaught) Exception.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - objects
```
protected final ConcurrentMap<K,AccessTimeObjectHolder<V>> objects
```
  - jamPolicy
```
protected final JamPolicy jamPolicy
```
  - loader
```
protected final javax.cache.integration.CacheLoader<K,V> loader
```
- Constructor Detail
  - Cache
```
public Cache(TCacheFactory factory,
             Builder<K,V> builder)
```
    Construct a Cache, using the given configuration from the Builder.
    
    Parameters:
    
    builder - The builder containing the configuration
    
    factory - The factory, in which this Cache will be registered.
- Method Detail
  - evictionExtraSpace
```
protected int evictionExtraSpace(Builder<K,V> builder)
```
    Returns a size factor for the map for the specific eviction strategy of this Cache. The default implementation returns 0, as it does not use any extra space.
    
    Parameters:
    
    builder - The builder containing the configuration
    
    Returns:
    
    The number of extra elements required in the storage Map.
  - id
```
public String id()
```
  - configuration
```
public TriavaCacheConfiguration<K,V,? extends Builder<K,V>> configuration()
```
  - close
```
public final void close()
```
    Closes the cache and removes it from the associated CacheManager. After calling this method, the cache cannot be used any longer.
  - isClosed
```
public boolean isClosed()
```
  - joinSimple
```
public boolean joinSimple(Thread thread,
                          long millis,
                          int nanos)
```
    Waits at most millis milliseconds plus nanos nanoseconds for the given thread to die. If the calling thread gets interrupted during the call to this method, the method will preserve the interruption status, but will continue running until the given thread has stopped or the timeout has passed.
    
    Parameters:
    
    thread - The target thread
    
    millis - The number of milliseconds to wait
    
    nanos - The number of nanoseconds to wait
    
    Returns:
    
    true if the thread is not running, false if it is alive.
  - put
```
public void put(K key,
                V value)
```
    Add an object to the cache under the given key, using the default idle time and default cache time.
    
    Parameters:
    
    key - The key
    
    value - The value
  - getAndPut
```
public V getAndPut(K key,
                   V value)
```
    Add an object to the cache under the given key, using the default idle time and default cache time. Returns the previous value for the key, or null if no previous entry was present.
    
    Parameters:
    
    key - The key
    
    value - The value
    
    Returns:
    
    The previous value
  - put
```
public void put(K key,
                V value,
                int idleTime,
                int cacheTime,
                TimeUnit timeUnit)
```
    Add an object to the cache under the given key with the given idle and cache times.
    
    Parameters:
    
    key - The key
    
    value - The value
    
    idleTime - The idle time in seconds
    
    cacheTime - The cache time in seconds
    
    timeUnit - The TimeUnit for both idleTime and cacheTime
  - putIfAbsent
```
public V putIfAbsent(K key,
                     V value,
                     int idleTime,
                     int cacheTime,
                     TimeUnit timeUnit)
```
    The same like put(Object, Object, int, int, TimeUnit), but uses ConcurrentMap.putIfAbsent(Object, Object) to actually write the data in the backing ConcurrentMap. For the sake of the Cache hit or miss statistics this method is a treated as a read operation and thus updates the hit or miss counters. Rationale is that the putIfAbsent() result is usually evaluated by the caller.
    
    Parameters:
    
    key - The key
    
    value - The value
    
    idleTime - Maximum idle time in seconds
    
    cacheTime - Maximum cache time in seconds
    
    timeUnit - The TimeUnit for both idleTime and cacheTime
    
    Returns:
    
    See ConcurrentHashMap.putIfAbsent(Object, Object)
  - putIfAbsent
```
public V putIfAbsent(K key,
                     V value)
```
    The same like putIfAbsent(Object, Object, int, int, TimeUnit), but uses the default idle and cache times. The cache time will use the cache time spread if this cache is configured to use it.
    
    Parameters:
    
    key - The key
    
    value - The value
    
    Returns:
    
    See ConcurrentHashMap.putIfAbsent(Object, Object)
  - putToMap
```
protected AccessTimeObjectHolder<V> putToMap(K key,
                                             V data,
                                             long idleTime,
                                             long cacheTime,
                                             boolean putIfAbsent,
                                             boolean returnEffectiveHolder)
```
    Puts the value wrapped in a AccessTimeObjectHolder in the map and returns it. What exactly is returned depends on the value of returnEffectiveHolder. If putIfAbsent is true, the put is done in the fashion of ConcurrentMap.putIfAbsent(Object, Object), otherwise like Map.put(Object, Object).
    
    Parameters:
    
    key - The key
    
    data - The value
    
    idleTime - in milliseconds
    
    cacheTime - Max Cache time in milliseconds
    
    putIfAbsent - Defines the behavior when the key is already present. See method documentation.
    
    returnEffectiveHolder - If true, the holder object of the object in the Map is returned. If returnEffectiveHolder is false, the returned value is like described in Map.put(Object, Object).
    
    Returns:
    
    The holder reference, as described in the returnEffectiveHolder parameter
  - gatedHolder
```
protected AccessTimeObjectHolder<V> gatedHolder(AccessTimeObjectHolder<V> holder)
```
  - getAndReplace
```
public V getAndReplace(K key,
                       V value)
```
    Replace the entry stored by key with the given value.
    
    Parameters:
    
    key - The key
    
    value - The value to write
    
    Returns:
    
    The old value. null if there was no mapping for the key.
    
    See Also:
    
    Cache.getAndReplace(Object, Object)
  - replace
```
public ChangeStatus replace(K key,
                            V oldValue,
                            V newValue)
```
  - ensureFreeCapacity
```
protected boolean ensureFreeCapacity()
```
    Returns whether there is capacity for at least one more element. The default implementation always returns true. Derived classes that implement a Cache limit (LFU, LRU, ...) can either create free room or return false if the Cache is full.
    
    Returns:
    
    true, if there is capacity left
  - get
```
public V get(K key)
      throws RuntimeException
```
    Gets cached object for the given key, or null if this Cache contains no mapping for the key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. There is no operation to distinguish these two cases. Throws NullPointerException if pKey is null.
    
    Parameters:
    
    key - The key
    
    Returns:
    
    The value
    
    Throws:
    
    RuntimeException - if key is not present and the loader threw an Exception.
    
    NullPointerException - if key is null.
  - fillCacheStatistics
```
protected TCacheStatisticsInterface fillCacheStatistics(TCacheStatisticsInterface cacheStatistic)
```
    Fills the given cache statistics object.
    
    Parameters:
    
    cacheStatistic - The statistics object to fill
    
    Returns:
    
    The CacheStatistic object
  - statistics
```
public TCacheStatistics statistics()
```
  - getCacheHitrate
```
public float getCacheHitrate()
```
    Returns the Cache hit rate. The returned value is the average of the last n measurements (2012-10-16: n=5). Implementation note: This method should be called in regular intervals, because it also updates its "hit rate statistics array". Future direction: This method overlaps functionality, which is now provided by SlidingWindowCounter. Thus migrate the hit rate to use SlidingWindowCounter.
    
    Returns:
    
    The Cache hit rate in percent (0-100)
  - clear
```
public void clear()
```
    Removes all entries from the Cache without notifying Listeners
  - stopAndClear
```
protected String stopAndClear(long millis)
```
  - activateTimeSource
```
protected TimeSource activateTimeSource()
```
    Returns the TimeSource for this Cache. The TimeSource is used for any situation where the current time is required, for example the input date for a cache entry or on getting the current time when doing expiration. Instantiates the TimeSource if it is not yet there.
    
    Returns:
    
    The TimeSource for this Cache.
  - uncaughtException
```
public void uncaughtException(Thread thread,
                              Throwable throwable)
```
    This is called, if the CleanupThread goes down on an unexpected (uncaught) Exception.
    
    Specified by:
    
    uncaughtException in interface Thread.UncaughtExceptionHandler
  - size
```
public int size()
```
    Returns:
    
    count of cached objects
  - remove
```
public boolean remove(K key,
                      V value)
```
    Removes the object with given key, if stored in the Cache. Returns whether it was actually removed.
    
    Parameters:
    
    key - The key
    
    value - The value
    
    Returns:
    
    The value that was stored for the given key or null
  - remove
```
public V remove(K key)
```
    Removes the mapping for the given key, and returns the value that was stored for it. Returns null if there was no value for the key stored.
    Implementation note: The return value reflects the "remove-from-map" outcome, not the "release". This is to fulfill the JSR Spec and TCK. In the future it should be checked again whether we can make it reflect the "release" again, as it would be cleaner (i.e.: atomic, more consistent)
    
    Parameters:
    
    key - The key
    
    Returns:
    
    The value that was stored for the given key or null
  - removeAndRelease
```
protected V removeAndRelease(K key)
```
    Removes the mapping for the given key, and releases the associated holder. This method is thread-safe and has atomic-like behavior: If two threads call this method, only one will be returned true.
    Implementation note: The return value reflects the "release" outcome, not the removal from the Map. This is done, as the "release" operation is a GATE, and it can only be passed once per Holder.
    
    Parameters:
    
    key - The key
    
    Returns:
    
    true, if this call released the holder for the given key.
  - expireUntil
```
public void expireUntil(K key,
                        int maxDelay,
                        TimeUnit timeUnit)
```
    Schedule the entry for the given key for expiration. The time will be chosen randomly between immediately and the given maximum delay. The chosen time will never increase the natural expiration time of the object. If the given maximum delay is 0, the entry is set to expire immediately.
    This method is especially useful if many cache entries are to be invalidated, and fetching data is an expensive operation. As each call to this method will chose a different expiration time, expiration and thus possible re-fetching will spread over a longer time, and helps to avoid resource overload (like DB, REST Service, ...).
    
    Parameters:
    
    key - The key for the entry to expire
    
    maxDelay - The maximum delay time until the object will be expired
    
    timeUnit - The time unit for maxDelay
    
    Throws:
    
    IllegalArgumentException - - if the maxDelay value is < 0
  - iterator
```
public TCacheHolderIterator<K,V> iterator()
```
    Returns an Iterator which can be used to traverse all entries of the Cache. The values of the entry are of type TCacheHolder<V>.
    WARNING!!! Up to v0.9.9, the value reflects the actual state and may change after retrieving. For example accessTime can change if the entry is accessed, and value.get() may return null if it is expired. This behavior will change with v1.0, and the returned value will we immutable.
    
    Returns:
    
    The Iterator
  - iteratorWithTouch
```
public TCacheHolderIterator<K,V> iteratorWithTouch()
```
    Returns an Iterator which can be used to traverse all entries of the Cache. The behavior is identical with iterator(), but the traversed elements are treated as touched. This means, access time is updated and hit count statistics are maintained.
    WARNING!!! Up to v0.9.9, the value reflects the actual state and may change after retrieving. For example accessTime can change if the entry is accessed, and value.get() may return null if it is expired. This behavior will change with v1.0, and the returned value will we immutable.
    
    Returns:
    
    The Iterator
  - keySet
```
public Collection<K> keySet()
```
    Returns a thread-safe unmodifiable collection of the keys.
    
    Returns:
    
    The keys as a Collection
  - containsKey
```
public boolean containsKey(K key)
```
    Returns true if this Cache contains a mapping for the specified key.
    
    Parameters:
    
    key - The key
    
    Returns:
    
    true if this Cache contains a mapping for the specified key
    
    See Also:
    
    Map.containsKey(Object)
  - setLogger
```
public static void setLogger(TriavaLogger logger)
```
    Sets the logger that will be used for all Cache instances. Changing the logger during runtime has immediate effect.
    
    Parameters:
    
    logger - The logger to use
  - reportSize
```
public CacheSizeInfo reportSize(ObjectSizeCalculatorInterface objectSizeCalculator)
```
    Measures the number of elements and the size of this Cache in bytes and logs it. The number of elements is logged twice. Once before and once after the size measurement. This will help to see how much the content has changed during the measurement.
    
    Parameters:
    
    objectSizeCalculator - The implementation to use
    
    Returns:
    
    The size information of this Cache
  - jsr107cache
```
public TCacheJSR107<K,V> jsr107cache()
```
    Returns a JSR107 compliant view on this Cache. The returned instance is a view of the native tCache, so any operation on it or this will be visible by the other instance.
    
    Returns:
    
    A JSR107 compliant view on this Cache
  - enableStatistics
```
public void enableStatistics(boolean enable)
```
    Enables or disables statistics. If enabled, the statistics are available both via statistics() and also by JSR107 compliant MXBeans. Disabling statistics will discard all statistics.
    
    Parameters:
    
    enable - true for enabling statistics.
  - enableManagement
```
public void enableManagement(boolean enable)
```
  - isStatisticsEnabled
```
public boolean isStatisticsEnabled()
```
  - isManagementEnabled
```
public boolean isManagementEnabled()
```
  - cacheWriter
```
public javax.cache.integration.CacheWriter<K,V> cacheWriter()
```
    Specified by:
    
    cacheWriter in interface ActionContext<K,V>
  - listeners
```
public ListenerCollection<K,V> listeners()
```
    Specified by:
    
    listeners in interface ActionContext<K,V>
  - statisticsCalculator
```
public StatisticsCalculator statisticsCalculator()
```
    Specified by:
    
    statisticsCalculator in interface ActionContext<K,V>
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - configToString
```
protected String configToString()
```

Class Cache<K,V>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

objects

jamPolicy

loader

Constructor Detail

Cache

Method Detail

evictionExtraSpace

id

configuration

close

isClosed

joinSimple

put

getAndPut

put

putIfAbsent

putIfAbsent

putToMap

gatedHolder

getAndReplace

replace

ensureFreeCapacity

get

fillCacheStatistics

statistics

getCacheHitrate

clear

stopAndClear

activateTimeSource

uncaughtException

size

remove

remove

removeAndRelease

expireUntil

iterator

iteratorWithTouch

keySet

containsKey

setLogger

reportSize

jsr107cache

enableStatistics

enableManagement

isStatisticsEnabled

isManagementEnabled

cacheWriter

listeners

statisticsCalculator

toString

configToString