Cache (ehcache 3.2.3 API)

Type Parameters:

K - the key type for the cache

V - the value type for the cache

All Superinterfaces:

java.lang.Iterable<Cache.Entry<K,V>>

All Known Subinterfaces:

PersistentUserManagedCache<K,V>, UserManagedCache<K,V>
```
public interface Cache<K,V>
extends java.lang.Iterable<Cache.Entry<K,V>>
```
Defines all operational methods to create, access, update and delete mappings of key to value.
In order to function, cache keys must respect the hash code and equals contracts. This contract is what will be used to lookup values based on key.

A Cache is not a map, mostly because it has the following two concepts linked to mappings:
- Eviction: A Cache has a capacity constraint and in order to honor it, a Cache can evict (remove) a mapping at any point in time. Note that eviction may occur before maximum capacity is reached.
- Expiry: Data in a Cache can be configured to expire after some time. There is no way for a Cache user to differentiate from the API between a mapping being absent or expired.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static interface Cache.Entry<K,V>
A mapping of key to value held in a Cache.

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`Cache.Entry<K,V>` A mapping of key to value held in a `Cache`.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`clear()` Removes all mappings currently present in the `Cache`.
`boolean`	`containsKey(K key)` Checks whether a mapping for the given key is present, without retrieving the associated value.
`V`	`get(K key)` Retrieves the value currently mapped to the provided key.
`java.util.Map<K,V>`	`getAll(java.util.Set<? extends K> keys)` Retrieves all values associated with the given key set.
`CacheRuntimeConfiguration<K,V>`	`getRuntimeConfiguration()` Exposes the `CacheRuntimeConfiguration` associated with this Cache instance.
`void`	`put(K key, V value)` Associates the given value to the given key in this `Cache`.
`void`	`putAll(java.util.Map<? extends K,? extends V> entries)` Associates all the provided key:value pairs.
`V`	`putIfAbsent(K key, V value)` Maps the specified key to the specified value in this cache, unless a non-expired mapping already exists.
`void`	`remove(K key)` Removes the value, if any, associated with the provided key.
`boolean`	`remove(K key, V value)` Removes the entry for a key only if currently mapped to the given value and the entry is not expired.
`void`	`removeAll(java.util.Set<? extends K> keys)` Removes any associated value for the given key set.
`V`	`replace(K key, V value)` Replaces the entry for a key only if currently mapped to some value and the entry is not expired.
`boolean`	`replace(K key, V oldValue, V newValue)` Replaces the entry for a key only if currently mapped to the given value and the entry is not expired.

Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator

- Method Detail
  - get
```
V get(K key)
throws CacheLoadingException
```
    Retrieves the value currently mapped to the provided key.
    
    Parameters:
    
    key - the key, may not be null
    
    Returns:
    
    the value mapped to the key, null if none
    
    Throws:
    
    java.lang.NullPointerException - if the provided key is null
    
    CacheLoadingException - if the CacheLoaderWriter associated with this cache was invoked and threw an Exception
  - put
```
void put(K key,
         V value)
  throws CacheWritingException
```
    Associates the given value to the given key in this Cache.
    
    Parameters:
    
    key - the key, may not be null
    
    value - the value, may not be null
    
    Throws:
    
    java.lang.NullPointerException - if either key or value is null
    
    CacheWritingException - if the CacheLoaderWriter associated with this cache threw an Exception while writing the value for the given key to the underlying system of record.
  - containsKey
```
boolean containsKey(K key)
```
    Checks whether a mapping for the given key is present, without retrieving the associated value.
    
    Parameters:
    
    key - the key, may not be null
    
    Returns:
    
    true if a mapping is present, false otherwise
    
    Throws:
    
    java.lang.NullPointerException - if the provided key is null
  - remove
```
void remove(K key)
     throws CacheWritingException
```
    Removes the value, if any, associated with the provided key.
    
    Parameters:
    
    key - the key to remove the value for, may not be null
    
    Throws:
    
    java.lang.NullPointerException - if the provided key is null
    
    CacheWritingException - if the CacheLoaderWriter associated with this cache threw an Exception while removing the value for the given key from the underlying system of record.
  - getAll
```
java.util.Map<K,V> getAll(java.util.Set<? extends K> keys)
                   throws BulkCacheLoadingException
```
    Retrieves all values associated with the given key set.
    
    Parameters:
    
    keys - keys to query for, may not contain null
    
    Returns:
    
    a map from keys to values or null if the key was not mapped
    
    Throws:
    
    java.lang.NullPointerException - if the Set or any of the contained keys are null.
    
    BulkCacheLoadingException - if loading some or all values failed
  - putAll
```
void putAll(java.util.Map<? extends K,? extends V> entries)
     throws BulkCacheWritingException
```
    Associates all the provided key:value pairs.
    
    Parameters:
    
    entries - key:value pairs to associate, keys or values may not be null
    
    Throws:
    
    java.lang.NullPointerException - if the Map or any of the contained keys or values are null.
    
    BulkCacheWritingException - if the CacheLoaderWriter associated with this cache threw an Exception while writing given key:value pairs to the underlying system of record.
  - removeAll
```
void removeAll(java.util.Set<? extends K> keys)
        throws BulkCacheWritingException
```
    Removes any associated value for the given key set.
    
    Parameters:
    
    keys - keys to remove values for, may not be null
    
    Throws:
    
    java.lang.NullPointerException - if the Set or any of the contained keys are null.
    
    BulkCacheWritingException - if the CacheLoaderWriter associated with this cache threw an Exception while removing mappings for given keys from the underlying system of record.
  - clear
```
void clear()
```
    Removes all mappings currently present in the Cache.
    It does so without invoking the CacheLoaderWriter or any registered CacheEventListener instances. This is not an atomic operation and can potentially be very expensive.
  - putIfAbsent
```
V putIfAbsent(K key,
              V value)
       throws CacheLoadingException,
              CacheWritingException
```
    Maps the specified key to the specified value in this cache, unless a non-expired mapping already exists.
    This is equivalent to
```
   if (!cache.containsKey(key))
       cache.put(key, value);
       return null;
   else
       return cache.get(key);
 
```
    except that the action is performed atomically.
    
    The value can be retrieved by calling the get method with a key that is equal to the original key.
    Neither the key nor the value can be null.
    Parameters:
    
    key - key with which the specified value is to be associated
    
    value - value to be associated with the specified key
    
    Returns:
    
    the value to which the specified key was previously mapped, or null if no such mapping existed or the mapping was expired
    
    Throws:
    
    java.lang.NullPointerException - if any of the arguments is null
    
    CacheWritingException - if the CacheLoaderWriter associated with this cache threw an Exception while writing the value for the given key to the underlying system of record.
    
    CacheLoadingException - if the CacheLoaderWriter associated with this cache was invoked and threw an Exception
  - remove
```
boolean remove(K key,
               V value)
        throws CacheWritingException
```
    Removes the entry for a key only if currently mapped to the given value and the entry is not expired.
    This is equivalent to
```
   if (cache.containsKey(key) && cache.get(key).equals(value)) {
       cache.remove(key);
       return true;
   } else return false;
 
```
    except that the action is performed atomically.
    
    The key cannot be null.
    Parameters:
    
    key - key with which the specified value is associated
    
    value - value expected to be removed
    
    Returns:
    
    true if the value was successfully removed
    
    Throws:
    
    java.lang.NullPointerException - if any of the arguments is null
    
    CacheWritingException - if the CacheLoaderWriter associated with this cache threw an Exception while removing the value for the given key from the underlying system of record.
  - replace
```
V replace(K key,
          V value)
   throws CacheLoadingException,
          CacheWritingException
```
    Replaces the entry for a key only if currently mapped to some value and the entry is not expired.
    This is equivalent to
```
   V oldValue = cache.get(key);
   if (oldValue != null) {
     cache.put(key, value);
   }
   return oldValue; 
```
    except that the action is performed atomically.
    
    Neither the key nor the value can be null.
    Parameters:
    
    key - of the value to be replaced
    
    value - the new value
    
    Returns:
    
    the existing value that was associated with the key, or null if no such mapping existed or the mapping was expired
    
    Throws:
    
    java.lang.NullPointerException - if any of the arguments is null
    
    CacheWritingException - if the CacheLoaderWriter associated with this cache threw an Exception while writing the value for the given key to the underlying system of record.
    
    CacheLoadingException - if the CacheLoaderWriter associated with this cache was invoked and threw an Exception
  - replace
```
boolean replace(K key,
                V oldValue,
                V newValue)
         throws CacheLoadingException,
                CacheWritingException
```
    Replaces the entry for a key only if currently mapped to the given value and the entry is not expired.
    This is equivalent to
```
   if (cache.containsKey(key) && cache.get(key).equals(oldValue)) {
       cache.put(key, newValue);
       return true;
   } else return false;
```
    except that the action is performed atomically.
    
    Neither the key nor the value can be null.
    Parameters:
    
    key - key with which the specified value is associated
    
    oldValue - value expected to be associated with the specified key
    
    newValue - value to be associated with the specified key
    
    Returns:
    
    true if the oldValue was successfully replaced by the newValue
    
    Throws:
    
    java.lang.NullPointerException - if any of the arguments is null
    
    CacheWritingException - if the CacheLoaderWriter associated with this cache threw an Exception while writing the value for the given key to the underlying system of record.
    
    CacheLoadingException - if the CacheLoaderWriter associated with this cache was invoked and threw an Exception
  - getRuntimeConfiguration
```
CacheRuntimeConfiguration<K,V> getRuntimeConfiguration()
```
    Exposes the CacheRuntimeConfiguration associated with this Cache instance.
    
    Returns:
    
    the configuration currently in use

Interface Cache<K,V>

Nested Class Summary

Method Summary

Methods inherited from interface java.lang.Iterable

Method Detail

get

put

containsKey

remove

getAll

putAll

removeAll

clear

putIfAbsent

remove

replace

replace

getRuntimeConfiguration