Cache (Commons Core 1.0.2 API)

Type Parameters:

K - the type of keys maintained by this cache

V - the type of mapped values
```
@ThreadSafe
 @ParametersAreNonnullByDefault
public interface Cache<K,V>
```
A semi-persistent mapping from keys to values. Cache entries are manually added using get(Object, Function) or put(Object, Object), and are stored in the cache until either evicted or manually invalidated.
Implementations of this interface are expected to be thread-safe, and can be safely accessed by multiple concurrent threads.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`ConcurrentMap<K,V>`	`asMap()` Returns a view of the entries stored in this cache as a thread-safe map.
`void`	`cleanUp()` Performs any pending maintenance operations needed by the cache.
`boolean`	`contains(K key)` Returns `true` if this map contains a mapping for the specified `key`.
`V`	`get(K key)` Returns the value associated with the `key` in this cache, or `null` if there is no cached value for the `key`.
`V`	`get(K key, Function<? super K,? extends V> mappingFunction)` Returns the value associated with the `key` in this cache, obtaining that value from the `mappingFunction` if necessary.
`Map<K,V>`	`getAll(Iterable<? extends K> keys)` Returns a map of the values associated with the `keys` in this cache.
`void`	`invalidate(K key)` Discards any cached value for the `key`.
`void`	`invalidateAll()` Discards all entries in the cache.
`void`	`invalidateAll(Iterable<? extends K> keys)` Discards any cached values for the `keys`.
`void`	`put(K key, V value)` Associates the `value` with the `key` in this cache.
`void`	`putAll(Map<? extends K,? extends V> map)` Copies all of the mappings from the specified map to the cache.
`void`	`putIfAbsent(K key, V value)` Associates the `value` with the `key` in this cache, only if the `key` does not already exist.
`void`	`refresh(K key)` Loads a new value for the `key`, asynchronously.
`long`	`size()` Returns the approximate number of entries in this cache.
`CacheStats`	`stats()` Returns a current snapshot of this cache's cumulative statistics.

- Method Detail
  - get
```
V get(K key)
```
    Returns the value associated with the key in this cache, or null if there is no cached value for the key.
    
    Parameters:
    
    key - the key whose associated value is to be returned
    
    Returns:
    
    the value to which the specified key is mapped, or null if this map contains no mapping for the key
  - get
```
V get(K key,
      Function<? super K,? extends V> mappingFunction)
```
    Returns the value associated with the key in this cache, obtaining that value from the mappingFunction if necessary.
    If the specified key is not already associated with a value, attempts to compute its value using the given mappingFunction and enters it into this cache unless null. The entire method invocation is performed atomically, so the function is applied at most once per key.
    
    Parameters:
    
    key - the key with which the specified value is to be associated
    
    mappingFunction - the function to compute a value
    
    Returns:
    
    the current (existing or computed) value associated with the specified key, or null if the computed value is null
    
    Throws:
    
    IllegalStateException - if the computation detectably attempts a recursive update to this cache that would otherwise never complete
    
    RuntimeException - if the mappingFunction does so, in which case the mapping is left unestablished
  - getAll
```
@Nonnull
Map<K,V> getAll(Iterable<? extends K> keys)
```
    Returns a map of the values associated with the keys in this cache. The returned map will only contain entries which are already present in the cache.
    
    Parameters:
    
    keys - the keys whose associated values are to be returned
    
    Returns:
    
    the unmodifiable mapping of keys to values for the specified keys found in this cache
  - put
```
void put(K key,
         V value)
```
    Associates the value with the key in this cache. If the cache previously contained a value associated with the key, the old value is replaced by the new value.
    
    Parameters:
    
    key - the key with which the specified value is to be associated
    
    value - value to be associated with the specified key
  - putIfAbsent
```
void putIfAbsent(K key,
                 V value)
```
    Associates the value with the key in this cache, only if the key does not already exist. If the cache previously contained a value associated with the key, then the call does nothing.
    
    Parameters:
    
    key - the key with which the specified value is to be associated
    
    value - value to be associated with the specified key
  - putAll
```
void putAll(Map<? extends K,? extends V> map)
```
    Copies all of the mappings from the specified map to the cache. The effect of this call is equivalent to that of calling put(Object, Object) on this map once for each mapping from key k to value v in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress.
    
    Parameters:
    
    map - the mappings to be stored in this cache
  - invalidate
```
void invalidate(K key)
```
    Discards any cached value for the key.
    
    Parameters:
    
    key - the key whose mapping is to be removed from the cache
  - invalidateAll
```
void invalidateAll(Iterable<? extends K> keys)
```
    Discards any cached values for the keys.
    
    Parameters:
    
    keys - the keys whose associated values are to be removed
  - invalidateAll
```
void invalidateAll()
```
    Discards all entries in the cache.
  - contains
```
boolean contains(K key)
```
    Returns true if this map contains a mapping for the specified key.
    
    Parameters:
    
    key - key whose presence in this map is to be tested
    
    Returns:
    
    true if this map contains a mapping for the specified key
  - size
```
@Nonnegative
long size()
```
    Returns the approximate number of entries in this cache.
    
    Returns:
    
    the estimated number of mappings
  - refresh
```
void refresh(K key)
```
    Loads a new value for the key, asynchronously. While the new value is loading the previous value (if any) will continue to be returned by get(key) unless it is evicted. If the new value is loaded successfully it will replace the previous value in the cache; if an exception is thrown while refreshing the previous value will remain.
    
    Parameters:
    
    key - key with which a value may be associated
  - cleanUp
```
void cleanUp()
```
    Performs any pending maintenance operations needed by the cache.
  - asMap
```
@Nonnull
ConcurrentMap<K,V> asMap()
```
    Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to the map directly affect the cache.
    Iterators from the returned map are at least weakly consistent: they are safe for concurrent use, but if the cache is modified (including by eviction) after the iterator is created, it is undefined which of the changes (if any) will be reflected in that iterator.
    
    Returns:
    
    a thread-safe view of this cache supporting all of the optional Map operations
  - stats
```
@Nonnull
CacheStats stats()
```
    Returns a current snapshot of this cache's cumulative statistics. All statistics are initialized to zero, and are monotonically increasing over the lifetime of the cache.
    Due to the performance penalty of maintaining statistics, some implementations may not record the usage history immediately or at all.
    Warning: this cache may not be recording statistical data. For example, a cache created using CacheBuilder only does so if the CacheBuilder.recordStats() method was called. If statistics are not being recorded, a CacheStats instance with zero for all values is returned.
    
    Returns:
    
    the current snapshot of the statistics of this cache

Interface Cache<K,V>

Method Summary

Method Detail

get

get

getAll

put

putIfAbsent

putAll

invalidate

invalidateAll

invalidateAll

contains

size

refresh

cleanUp

asMap

stats