Cache (cache2k API 1.4.0.Final API)

Type Parameters:

K - type of the key

V - type of the stores values

All Superinterfaces:

AdvancedKeyValueSource<K,V>, AutoCloseable, Closeable, KeyValueSource<K,V>, KeyValueStore<K,V>

All Known Subinterfaces:

IntCache<V>, LongCache<V>

All Known Implementing Classes:

AbstractCache, ForwardingCache
```
public interface Cache<K,V>
extends KeyValueStore<K,V>, Closeable
```
A cache is similar to a map or a key value store, allowing to retrieve and update values which are associated to keys. In contrast to a HashMap the cache allows concurrent access and modification to its content and automatically controls the amount of entries in the cache to stay within configured resource limits.
A cache can be obtained via a Cache2kBuilder, for example:
```
    Cache<Long, List<String>> cache =
      new Cache2kBuilder<Long, List<String>>() {}
        .name("myCache")
        .eternal(true)
        .build();
 
```
Basic operation: To mutate and retrieve the cache content the operations put(K, V) and peek(K) can be used, for example:
```
    cache.put(1, "one");
    cache.put(2, "two");
    // might fail:
    assertTrue(cache.containsKey(1));
    assertEquals("two", cache.peek(2));
 
```
It is important to note that the two assertion in the above example may fail. A cache has not the same guarantees as a data storage, because it needs to remove content automatically as soon as resource limits are reached. This is called eviction.
Populating: A cache may automatically populate its contents via a CacheLoader. For typical read mostly caching this has several advantages, for details see CacheLoader. When using a cache loader the additional methods for mutating the cache directly may not be needed. Some methods, that do not interact with the loader such as containsKey(K) may be false friends. To make the code more obvious and protect against the accidental use of methods that do not invoke the loader transparently a subset interface, for example the KeyValueSource can be used.
CAS-Operations: The cache has a set of operations that examine an entry and do a mutation in an atomic way, for example putIfAbsent(K, V), containsAndRemove(K) and replaceIfEquals(K, V, V). To allow arbitrary semantics that operate atomically on an EntryProcessor can be implemented and executed via invoke(K, org.cache2k.processor.EntryProcessor<K, V, R>).
Compatibility: Future versions of cache2k may introduce new methods to this interface. To improve upward compatibility applications that need to implement this interface should use AbstractCache or ForwardingCache.
Author:

Jens Wilke

See Also:

to create a cache, to manage and retrieve created caches, cache2k User Guide

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`ConcurrentMap<K,V>`	`asMap()` Returns a map interface for operating with this cache.
`void`	`clear()` Clear the cache in a fast way, causing minimal disruption.
`void`	`clearAndClose()` This is currently identical to `close()`.
`void`	`close()` Free all resources and remove the cache from the CacheManager.
`V`	`computeIfAbsent(K key, Callable<V> callable)` If the specified key is not already associated with a value (or exception), call the provided task and associate it with the returned value.
`boolean`	`containsAndRemove(K key)` Removes the mapping for a key from the cache and returns `true` if it one was present.
`boolean`	`containsKey(K key)` Returns `true`, if there is a mapping for the specified key.
`Iterable<CacheEntry<K,V>>`	`entries()` Iterate all entries in the cache.
`void`	`expireAt(K key, long millis)` Updates an existing not expired mapping to expire at the given point in time.
`V`	`get(K key)` Returns a value associated with the given key.
`Map<K,V>`	`getAll(Iterable<? extends K> keys)` Retrieve values from the cache associated with the provided keys.
`CacheManager`	`getCacheManager()` Return the cache manager for this cache instance.
`CacheEntry<K,V>`	`getEntry(K key)` Returns an entry that contains the cache value associated with the given key.
`String`	`getName()` A configured or generated name of this cache instance.
`CacheInfoMXBean`	`getStatistics()` Return cache statistics.
`<R> R`	`invoke(K key, EntryProcessor<K,V,R> entryProcessor)` Invoke a user defined function on a cache entry.
`<R> Map<K,EntryProcessingResult<R>>`	`invokeAll(Iterable<? extends K> keys, EntryProcessor<K,V,R> entryProcessor)` Invoke a user defined function on multiple cache entries specified by the `keys` parameter.
`boolean`	`isClosed()` Returns `true` if cache was closed or closing is in progress.
`Iterable<K>`	`keys()` Iterate all keys in the cache.
`void`	`loadAll(Iterable<? extends K> keys, CacheOperationCompletionListener listener)` Asynchronously loads the given set of keys into the cache.
`V`	`peek(K key)` Returns the value associated to the given key.
`Map<K,V>`	`peekAll(Iterable<? extends K> keys)` Bulk version for `peek(Object)`
`V`	`peekAndPut(K key, V value)` Updates an existing cache entry for the specified key, so it associates the given value, or, insert a new cache entry for this key and value.
`V`	`peekAndRemove(K key)` Removes the mapping for a key from the cache if it is present.
`V`	`peekAndReplace(K key, V value)` Replaces the entry for a key only if currently mapped to some value.
`CacheEntry<K,V>`	`peekEntry(K key)` Returns an entry that contains the cache value associated with the given key.
`void`	`prefetch(K key)` Notifies the cache about the intention to retrieve the value for this key in the near future.
`void`	`prefetchAll(Iterable<? extends K> keys, CacheOperationCompletionListener listener)` Notifies the cache about the intention to retrieve the value for this key in the near future.
`void`	`put(K key, V value)` Inserts a new value associated with the given key or updates an existing association of the same key with the new value.
`void`	`putAll(Map<? extends K,? extends V> valueMap)` Insert all elements of the map into the cache.
`boolean`	`putIfAbsent(K key, V value)` If the specified key is not already associated with a value, associate it with the given value.
`void`	`reloadAll(Iterable<? extends K> keys, CacheOperationCompletionListener listener)` Asynchronously loads the given set of keys into the cache.
`void`	`remove(K key)` Removes the mapping for a key from the cache if it is present.
`void`	`removeAll()` Removes all cache contents.
`void`	`removeAll(Iterable<? extends K> keys)` Removes a set of keys.
`boolean`	`removeIfEquals(K key, V expectedValue)` Remove the mapping if the stored value is the equal to the comparison value.
`boolean`	`replace(K key, V value)` Replaces the entry for a key only if currently mapped to some value.
`boolean`	`replaceIfEquals(K key, V oldValue, V newValue)` Replaces the entry for a key only if currently mapped to a given value.
`<X> X`	`requestInterface(Class<X> type)` Request an alternative interface for this cache instance.
`String`	`toString()` Returns internal information.

- Method Detail
  - getName
```
String getName()
```
    A configured or generated name of this cache instance. A cache in close state will still return its name.
    
    Returns:
    
    name of this cache
    
    See Also:
    
    Cache2kBuilder.name(String)
  - get
```
V get(K key)
```
    Returns a value associated with the given key. If no value is present or it is expired the cache loader is invoked, if configured, or null is returned.
    If the CacheLoader is invoked, subsequent requests of the same key will block until the loading is completed. Details see CacheLoader.
    As an alternative peek(K) can be used if the loader should not be invoked.
    
    Specified by:
    
    get in interface KeyValueSource<K,V>
    
    Parameters:
    
    key - key with which the specified value is associated
    
    Returns:
    
    the value associated with the specified key, or null if there was no mapping for the key. (If nulls are permitted a null can also indicate that the cache previously associated null with the key)
    
    Throws:
    
    ClassCastException - if the class of the specified key prevents it from being stored in this cache
    
    NullPointerException - if the specified key is null
    
    IllegalArgumentException - if some property of the specified key prevents it from being stored in this cache
    
    CacheLoaderException - if the loading produced an exception .
    
    See Also:
    
    get(Object)
  - getEntry
```
CacheEntry<K,V> getEntry(K key)
```
    Returns an entry that contains the cache value associated with the given key. If no entry is present or the value is expired, either the loader is invoked or null is returned.
    If the loader is invoked, subsequent requests of the same key will block until the loading is completed, details see CacheLoader
    In case the cache loader yields an exception, the entry object will be returned. The exception can be retrieved via CacheEntry.getException().
    If null values are present the method can be used to check for an existent mapping and retrieve the value in one API call.
    The alternative method peekEntry(K) can be used if the loader should not be invoked.
    
    Parameters:
    
    key - key to retrieve the associated with the cache entry
    
    Returns:
    
    An entry representing the cache mapping. Multiple calls for the same key may return different instances of the entry object.
    
    Throws:
    
    ClassCastException - if the class of the specified key prevents it from being stored in this cache
    
    NullPointerException - if the specified key is null
    
    IllegalArgumentException - if some property of the specified key prevents it from being stored in this cache
  - prefetch
```
void prefetch(K key)
```
    Notifies the cache about the intention to retrieve the value for this key in the near future.
    The method will return immediately and the cache will load the value asynchronously if not yet present in the cache. Prefetching is done via a separate thread pool if specified via Cache2kBuilder.prefetchExecutor(Executor).
    If no CacheLoader is defined the method will do nothing.
    This method doesn't throw an exception in case the loader produced an exception. Exceptions will be propagated when the value is accessed.
    
    Specified by:
    
    prefetch in interface AdvancedKeyValueSource<K,V>
    
    Parameters:
    
    key - the key that should be loaded, not null
    
    See Also:
    
    Cache2kBuilder.loaderThreadCount(int), Cache2kBuilder.prefetchExecutor(Executor)
  - prefetchAll
```
void prefetchAll(Iterable<? extends K> keys,
                 CacheOperationCompletionListener listener)
```
    Notifies the cache about the intention to retrieve the value for this key in the near future.
    The method will return immediately and the cache will load the value asynchronously if not yet present in the cache. Prefetching is done via a separate thread pool if specified via Cache2kBuilder.prefetchExecutor(Executor).
    If no CacheLoader is defined the method will do nothing.
    Exceptions from the loader will not be propagated via the listener. Exceptions will be propagated when the respective value is accessed.
    
    Specified by:
    
    prefetchAll in interface AdvancedKeyValueSource<K,V>
    
    Parameters:
    
    keys - the keys which should be loaded, not null
    
    listener - Listener interface that is invoked upon completion. May be null if no completion notification is needed.
    
    See Also:
    
    prefetchAll(Iterable, CacheOperationCompletionListener)
  - peek
```
V peek(K key)
```
    Returns the value associated to the given key.
    In contrast to get(Object) this method solely operates on the cache content and does not invoke the cache loader.
    API rationale: Consequently all methods that do not invoke the loader but return a value or a cache entry are prefixed with peek within this interface to make the different semantics immediately obvious by the name.
    
    Parameters:
    
    key - key with which the specified value is associated
    
    Returns:
    
    the value associated with the specified key, or null if there was no mapping for the key. (If nulls are permitted a null can also indicate that the cache previously associated null with the key)
    
    Throws:
    
    ClassCastException - if the class of the specified key prevents it from being stored in this cache
    
    NullPointerException - if the specified key is null
    
    IllegalArgumentException - if some property of the specified key prevents it from being stored in this cache
    
    CacheLoaderException - if the loading produced an exception .
  - peekEntry
```
CacheEntry<K,V> peekEntry(K key)
```
    Returns an entry that contains the cache value associated with the given key. If no entry is present or the value is expired, null is returned. The cache loader will not be invoked by this method.
    In case an exception is present, for example from a load operation carried out previously, the entry object will be returned. The exception can be retrieved via CacheEntry.getException().
    If null values are present the method can be used to check for an existent mapping and retrieve the value in one API call.
    
    Parameters:
    
    key - key to retrieve the associated with the cache entry
    
    Returns:
    
    An entry representing the cache mapping. Multiple calls for the same key may return different instances of the entry object.
    
    Throws:
    
    ClassCastException - if the class of the specified key prevents it from being stored in this cache
    
    NullPointerException - if the specified key is null
    
    IllegalArgumentException - if some property of the specified key prevents it from being stored in this cache
  - containsKey
```
boolean containsKey(K key)
```
    Returns true, if there is a mapping for the specified key.
    Effect on statistics: The operation does increase the usage counter if a mapping is present, but does not count as read and therefore does not influence miss or hit values.
    
    Parameters:
    
    key - key which association should be checked
    
    Returns:
    
    true, if this cache contains a mapping for the specified key
    
    Throws:
    
    ClassCastException - if the key is of an inappropriate type for this cache
    
    NullPointerException - if the specified key is null
  - put
```
void put(K key,
         V value)
```
    Inserts a new value associated with the given key or updates an existing association of the same key with the new value.
    If an ExpiryPolicy is specified in the cache configuration it is called and will determine the expiry time. If a CacheWriter is registered, then it is called with the new value. If the ExpiryPolicy or CacheWriter yield an exception the operation will be aborted and the previous mapping will be preserved.
    
    Specified by:
    
    put in interface KeyValueStore<K,V>
    
    Parameters:
    
    key - key with which the specified value is associated
    
    value - value to be associated with the specified key
    
    Throws:
    
    ClassCastException - if the class of the specified key or value prevents it from being stored in this cache.
    
    NullPointerException - if the specified key is null or the value is null and the cache does not permit null values
    
    IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this cache.
    
    CacheException - if the cache was unable to process the request completely, for example, if an exceptions was thrown by a CacheWriter
    
    See Also:
    
    put(Object, Object)
  - computeIfAbsent
```
V computeIfAbsent(K key,
                  Callable<V> callable)
```
    If the specified key is not already associated with a value (or exception), call the provided task and associate it with the returned value. This is equivalent to
```
 
 if (!cache.containsKey(key)) {
   V value = callable.call();
   cache.put(key, value);
   return value;
 } else {
   return cache.peek(key);
 }
```
    except that the action is performed atomically.
    See put(Object, Object) for the effects on the cache writer and expiry calculation.
    Statistics: If an entry exists this operation counts as a hit, if the entry is missing, a miss and put is counted.
    Exceptions: If call throws an exception the cache contents will not be modified and the exception is propagated. The customized exception propagator is not used for this method.
    Rationale: The Function interface that Map.computeIfAbsent uses is only available in Java 8. Callable is a useful fallback and we can use it directly for the Spring integration. A mismatch is that Callable.call() declares a checked exception but the cache access method do not.
    Parameters:
    
    key - key with which the specified value is to be associated
    
    callable - task that computes the value
    
    Returns:
    
    the associated value in the cache
    
    Throws:
    
    CacheLoaderException - if a checked exception is thrown it is wrapped into a CacheLoaderException
    
    RuntimeException - in case Callable.call() yields a runtime exception, this is thrown directly
    
    ClassCastException - if the class of the specified key or value prevents it from being stored in this cache
    
    NullPointerException - if the specified key is null or the value is null and the cache does not permit null values
    
    IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this cache
  - putIfAbsent
```
boolean putIfAbsent(K key,
                    V value)
```
    If the specified key is not already associated with a value, associate it with the given value. This is equivalent to
```
 
 if (!cache.containsKey(key)) {
   cache.put(key, value);
   return true;
 } else {
   return false;
 }
```
    except that the action is performed atomically.
    See put(Object, Object) for the effects on the cache writer and expiry calculation.
    Statistics: If an entry exists this operation counts as a hit, if the entry is missing, a miss and put is counted. This definition is identical to the JSR107 statistics semantics. This is not consistent with other operations like containsAndRemove(Object) and containsKey(Object) that don't update the hit and miss counter if solely the existence of an entry is tested and not the value itself is requested. This counting is subject to discussion and future change.
    Parameters:
    
    key - key with which the specified value is to be associated
    
    value - value to be associated with the specified key
    
    Returns:
    
    true, if no entry was present and the value was associated with the key
    
    Throws:
    
    ClassCastException - if the class of the specified key or value prevents it from being stored in this cache
    
    NullPointerException - if the specified key is null or the value is null and the cache does not permit null values
    
    IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this cache
  - peekAndReplace
```
V peekAndReplace(K key,
                 V value)
```
    Replaces the entry for a key only if currently mapped to some value. This is equivalent to
```
 
 if (cache.containsKey(key)) {
   cache.put(key, value);
   return cache.peek(key);
 } else
   return null;
 
```
    except that the action is performed atomically.
    As with peek(Object), no request to the CacheLoader is made, if no entry is associated to the requested key.
    Parameters:
    
    key - key with which the specified value is associated
    
    value - value to be associated with the specified key
    
    Returns:
    
    the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the cache previously associated null with the key)
    
    Throws:
    
    ClassCastException - if the class of the specified key or value prevents it from being stored in this cache
    
    NullPointerException - if the specified key is null or the value is null and the cache does not permit null values
    
    IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this cache
    
    CacheLoaderException - if the loading of the entry produced an exception, which was not suppressed and is not yet expired
  - replace
```
boolean replace(K key,
                V value)
```
    Replaces the entry for a key only if currently mapped to some value. This is equivalent to
```
 
 if (cache.containsKey(key)) {
   cache.put(key, value);
   return true
 } else
   return false;
 
```
    except that the action is performed atomically.
    Statistics: If an entry exists this operation counts as a hit, if the entry is missing, a miss and put is counted. This definition is identical to the JSR107 statistics semantics. This is not consistent with other operations like containsAndRemove(Object) and containsKey(Object) that don't update the hit and miss counter if solely the existence of an entry is tested and not the value itself is requested. This counting is subject to discussion and future change.
    Parameters:
    
    key - key with which the specified value is associated
    
    value - value to be associated with the specified key
    
    Returns:
    
    true if a mapping is present and the value was replaced. false if no entry is present and no action was performed.
    
    Throws:
    
    ClassCastException - if the class of the specified key or value prevents it from being stored in this cache.
    
    NullPointerException - if the specified key is null or the value is null and the cache does not permit null values
    
    IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this cache.
  - replaceIfEquals
```
boolean replaceIfEquals(K key,
                        V oldValue,
                        V newValue)
```
    Replaces the entry for a key only if currently mapped to a given value. This is equivalent to
```
 
 if (cache.containsKey(key) && Objects.equals(cache.get(key), oldValue)) {
   cache.put(key, newValue);
   return true;
 } else
   return false;
 
```
    except that the action is performed atomically.
    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 value was replaced
    
    Throws:
    
    ClassCastException - if the class of a specified key or value prevents it from being stored in this map
    
    NullPointerException - if a specified key or value is null, and this map does not permit null keys or values
    
    IllegalArgumentException - if some property of a specified key or value prevents it from being stored in this map
  - peekAndRemove
```
V peekAndRemove(K key)
```
    Removes the mapping for a key from the cache if it is present.
    Returns the value to which the cache previously associated the key, or null if the cache contained no mapping for the key.
    If the cache does permit null values, then a return value of null does not necessarily indicate that the cache contained no mapping for the key. It is also possible that the cache explicitly associated the key to the value null. This is equivalent to
```
 
  V tmp = cache.peek(key);
  cache.remove(key);
  return tmp;
 
```
    except that the action is performed atomically.
    As with peek(Object), no request to the CacheLoader is made, if no entry is associated to the requested key.
    Parameters:
    
    key - key whose mapping is to be removed from the cache
    
    Returns:
    
    the previous value associated with key, or null if there was no mapping for key.
    
    Throws:
    
    NullPointerException - if a specified key is null
    
    ClassCastException - if the key is of an inappropriate type for the cache. This check is optional depending on the cache configuration.
  - containsAndRemove
```
boolean containsAndRemove(K key)
```
    Removes the mapping for a key from the cache and returns true if it one was present.
    
    Parameters:
    
    key - key whose mapping is to be removed from the cache
    
    Returns:
    
    true if the cache contained a mapping for the specified key
    
    Throws:
    
    NullPointerException - if a specified key is null
    
    ClassCastException - if the key is of an inappropriate type for the cache. This check is optional depending on the cache configuration.
  - remove
```
void remove(K key)
```
    Removes the mapping for a key from the cache if it is present.
    If a writer is registered CacheWriter.delete(Object) will get called.
    These alternative versions of the remove operation exist:
    - containsAndRemove(Object), returning a success flag
    - peekAndRemove(Object), returning the removed value
    - removeIfEquals(Object, Object), conditional removal matching on the current value
    See KeyValueStore.remove(Object), for an explanation why no flag or object is returned.
    Specified by:
    
    remove in interface KeyValueStore<K,V>
    
    Parameters:
    
    key - key which mapping is to be removed from the cache, not null
    
    Throws:
    
    NullPointerException - if a specified key is null
    
    ClassCastException - if the key is of an inappropriate type for this map
    
    CacheWriterException - if the writer call failed
    
    See Also:
    
    remove(K)
  - removeIfEquals
```
boolean removeIfEquals(K key,
                       V expectedValue)
```
    Remove the mapping if the stored value is the equal to the comparison value.
    
    Parameters:
    
    key - key whose mapping is to be removed from the cache
    
    expectedValue - value that must match with the existing value in the cache
    
    Returns:
    
    true, if mapping was removed
    
    Throws:
    
    NullPointerException - if a specified key is null
    
    ClassCastException - if the key is of an inappropriate type for this map
  - removeAll
```
void removeAll(Iterable<? extends K> keys)
```
    Removes a set of keys. This has the same semantics of calling remove to every key, except that the cache is trying to optimize the bulk operation.
    
    Specified by:
    
    removeAll in interface KeyValueStore<K,V>
    
    Parameters:
    
    keys - a set of keys to remove
    
    Throws:
    
    NullPointerException - if a specified key is null
    
    See Also:
    
    removeAll(java.lang.Iterable<? extends K>)
  - peekAndPut
```
V peekAndPut(K key,
             V value)
```
    Updates an existing cache entry for the specified key, so it associates the given value, or, insert a new cache entry for this key and value. The previous value will returned, or null if none was available.
    Returns the value to which the cache previously associated the key, or null if the cache contained no mapping for the key.
    If the cache does permit null values, then a return value of null does not necessarily indicate that the cache contained no mapping for the key. It is also possible that the cache explicitly associated the key to the value null. This is equivalent to
```
 
  V tmp = cache.peek(key);
  cache.put(key, value);
  return tmp;
 
```
    except that the action is performed atomically.
    As with peek(Object), no request to the CacheLoader is made, if no entry is associated to the requested key.
    See put(Object, Object) for the effects on the cache writer and expiry calculation.
    Parameters:
    
    key - key with which the specified value is associated
    
    value - value to be associated with the specified key
    
    Returns:
    
    true if a mapping is present and the value was replaced. false if no entry is present and no action was performed.
    
    Throws:
    
    ClassCastException - if the class of the specified key or value prevents it from being stored in this cache.
    
    NullPointerException - if the specified key is null or the value is null and the cache does not permit null values
    
    IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this cache.
  - expireAt
```
void expireAt(K key,
              long millis)
```
    Updates an existing not expired mapping to expire at the given point in time. If there is no mapping associated with the key or it is already expired, this operation has no effect. The special values ExpiryTimeValues.NOW and ExpiryTimeValues.REFRESH also effect an entry that was just refreshed.
    If the expiry time is in the past, the entry will expire immediately and refresh ahead is triggered, if enabled.
    Although the special time value ExpiryTimeValues.NOW will lead to an effective removal of the cache entry, the writer is not called, since the method is for cache control only.
    The cache must be configured with a ExpiryPolicy or Cache2kBuilder.expireAfterWrite(long, TimeUnit) otherwise expiry timing is not available and this method will throw an exception. An immediate expire via ExpiryTimeValues.NOW is always working.
    
    Parameters:
    
    key - key with which the specified value is associated
    
    millis - Time in milliseconds since epoch when the entry should expire. Also see ExpiryTimeValues
    
    Throws:
    
    IllegalArgumentException - if no expiry was enabled during cache setup.
  - loadAll
```
void loadAll(Iterable<? extends K> keys,
             CacheOperationCompletionListener listener)
```
    Asynchronously loads the given set of keys into the cache. Only missing or expired values will be loaded.
    The cache uses multiple threads to load the values in parallel. If thread resources are not sufficient, meaning the used executor is throwing RejectedExecutionException the calling thread is used to produce back pressure.
    If no loader is defined, the method will throw an immediate exception.
    After the load is completed, the completion listener will be called, if provided.
    
    Parameters:
    
    keys - The keys to be loaded
    
    listener - Listener interface that is invoked upon completion. May be null if no completion notification is needed.
    
    Throws:
    
    UnsupportedOperationException - if no loader is defined
  - reloadAll
```
void reloadAll(Iterable<? extends K> keys,
               CacheOperationCompletionListener listener)
```
    Asynchronously loads the given set of keys into the cache. Always invokes load for all keys and replaces values already in the cache.
    The cache uses multiple threads to load the values in parallel. If thread resources are not sufficient, meaning the used executor is throwing RejectedExecutionException the calling thread is used to produce back pressure.
    If no loader is defined, the method will throw an immediate exception.
    After the load is completed, the completion listener will be called, if provided.
    
    Parameters:
    
    keys - The keys to be loaded
    
    listener - Listener interface that is invoked upon completion. May be null if no completion notification is needed.
    
    Throws:
    
    UnsupportedOperationException - if no loader is defined
  - invoke
```
<R> R invoke(K key,
             EntryProcessor<K,V,R> entryProcessor)
```
    Invoke a user defined function on a cache entry. For examples and further details consult the documentation of EntryProcessor and MutableCacheEntry.
    
    Type Parameters:
    
    R - type of the result
    
    Parameters:
    
    key - the key of the cache entry that should be processed
    
    entryProcessor - processor instance to be invoked
    
    Returns:
    
    result provided by the entry processor
    
    Throws:
    
    EntryProcessingException - if an exception happened inside EntryProcessor.process(MutableCacheEntry)
    
    See Also:
    
    EntryProcessor, MutableCacheEntry
  - invokeAll
```
<R> Map<K,EntryProcessingResult<R>> invokeAll(Iterable<? extends K> keys,
                                              EntryProcessor<K,V,R> entryProcessor)
```
    Invoke a user defined function on multiple cache entries specified by the keys parameter.
    The order of the invocation is unspecified. To speed up processing the cache may invoke the entry processor in parallel. For examples and further details consult the documentation of EntryProcessor and MutableCacheEntry.
    
    Type Parameters:
    
    R - type of the result
    
    Parameters:
    
    keys - the keys of the cache entries that should be processed
    
    entryProcessor - processor instance to be invoked
    
    Returns:
    
    map containing the invocation results for every cache key
    
    See Also:
    
    EntryProcessor, MutableCacheEntry
  - getAll
```
Map<K,V> getAll(Iterable<? extends K> keys)
```
    Retrieve values from the cache associated with the provided keys. If the value is not yet in the cache, the loader is invoked.
    Executing the request, the cache may do optimizations like utilizing multiple threads for invoking the loader or using the bulk methods on the loader. This is not yet fully exploited and will improve with further cache2k releases.
    Exception handling: The method may terminate normal, even if the cache loader failed to provide values for some keys. The cache will generally do everything to delay the propagation of the exception until the key is requested, to be most specific. If the loader has permanent failures this method may throw an exception immediately.
    The operation is not performed atomically. This operation may call different loader methods either CacheLoader.loadAll(Iterable, Executor) or CacheLoader.load(Object).
    Performance: A better technique is using prefetchAll(java.lang.Iterable<? extends K>, org.cache2k.CacheOperationCompletionListener) and then get(Object) to request the the values.
    
    Specified by:
    
    getAll in interface AdvancedKeyValueSource<K,V>
    
    Throws:
    
    NullPointerException - if one of the specified keys is null
    
    CacheLoaderException - in case the loader has permanent failures. Otherwise the exception is thrown when the key is requested.
    
    See Also:
    
    getAll(Iterable)
  - peekAll
```
Map<K,V> peekAll(Iterable<? extends K> keys)
```
    Bulk version for peek(Object)
    If the cache permits null values, the map will contain entries mapped to a null value.
    If the loading of an entry produced an exception, which was not suppressed and is not yet expired. This exception will be thrown as CacheLoaderException when the entry is accessed via the map interface.
    The operation is not performed atomically. Mutations of the cache during this operation may or may not affect the result.
    
    Throws:
    
    NullPointerException - if one of the specified keys is null
    
    IllegalArgumentException - if some property of the specified key prevents it from being stored in this cache
  - putAll
```
void putAll(Map<? extends K,? extends V> valueMap)
```
    Insert all elements of the map into the cache.
    See put(Object, Object) for information about the interaction with the CacheWriter and ExpiryPolicy
    
    Specified by:
    
    putAll in interface KeyValueStore<K,V>
    
    Parameters:
    
    valueMap - Map of keys with associated values to be inserted in the cache
    
    Throws:
    
    NullPointerException - if one of the specified keys is null
  - keys
```
Iterable<K> keys()
```
    Iterate all keys in the cache.
    Contract: The iteration is usable while concurrent operations happen on the cache. All entry keys will be iterated when present in the cache at the moment of the call to Iterable.iterator(). An expiration or mutation happening during the iteration, may or may not be reflected. Separate calls to Iterable.iterator() to the identical Iterable instance start a separate iteration. It is ensured that every key is only iterated once.
    The iterator itself is not thread safe. Calls to one iterator instance from different threads are illegal or need proper synchronization.
    Statistics: Iteration is neutral to the cache statistics.
    Efficiency: Iterating keys is faster as iterating complete entries.
  - entries
```
Iterable<CacheEntry<K,V>> entries()
```
    Iterate all entries in the cache.
    See keys() for the general iterator contract.
    Efficiency: Iterating entries is less efficient then just iterating keys. The cache needs to create a new entry object and employ some sort of synchronisation to supply a consistent and immutable entry.
    
    See Also:
    
    keys()
  - removeAll
```
void removeAll()
```
    Removes all cache contents. This has the same semantics of calling remove to every key, except that the cache is trying to optimize the bulk operation. Same as clear but listeners will be called.
  - clear
```
void clear()
```
    Clear the cache in a fast way, causing minimal disruption. Not calling the listeners.
  - clearAndClose
```
void clearAndClose()
```
    This is currently identical to close().
    This method is to future proof the API, when a persistence feature is added. In this case the method will stop cache operations and remove all stored external data.
    Rationale: The corresponding method in JSR107 is CacheManager.destroyCache(). Decided to put it on the cache interface, because: An application can finish its operation on a cache with one API call; to destroy all the cached data the cache must read the configuration and build its internal representation, which leads to a "half activated" cache; the additional call may lead to a race conditions.
  - close
```
void close()
```
    Free all resources and remove the cache from the CacheManager.
    The method is designed to free resources and finish operations as gracefully and fast as possible. Some cache operations take an unpredictable long time such as the call of the CacheLoader, so it may happen that the cache still has threads in use when this method returns.
    After close, subsequent cache operations will throw a IllegalStateException. Cache operations currently in progress, may or may not terminated with an exception. A subsequent call to close will not throw an exception.
    If all caches need to be closed it is more effective to use CacheManager.close()
    The next releases of cache2k may store cache entries between restarts. If an application will never use the cached content again, the method clearAndClose() should be used instead.
    
    Specified by:
    
    close in interface AutoCloseable
    
    Specified by:
    
    close in interface Closeable
  - getCacheManager
```
CacheManager getCacheManager()
```
    Return the cache manager for this cache instance.
  - isClosed
```
boolean isClosed()
```
    Returns true if cache was closed or closing is in progress.
  - toString
```
String toString()
```
    Returns internal information. This is an expensive operation, since internal statistics are collected. During the call, concurrent operations on the cache may be blocked. This method will not throw the IllegalStateException in case the cache is closed, but return the solely the cache name and no statistics.
    
    Overrides:
    
    toString in class Object
  - requestInterface
```
<X> X requestInterface(Class<X> type)
```
    Request an alternative interface for this cache instance.
  - asMap
```
ConcurrentMap<K,V> asMap()
```
    Returns a map interface for operating with this cache. Operations on the map affect the cache directly, as well as modifications on the cache will affect the map.
    The returned map supports null values if enabled via Cache2kBuilder.permitNullValues(boolean).
    The equals and hashCode methods of the Map are forwarded to the cache. A map is considered identical when from the same cache instance. This is not compatible to the general Map contract.
    Multiple calls to this method return a new object instance which is a wrapper of the cache instance. Calling this method is a cheap operation.
    The current ConcurrentMap implementation is minimalistic and not optimized for all usage aspects. Calling the cache methods directly could be more effective.
    
    Returns:
    
    ConcurrentMap wrapper for this cache instance
  - getStatistics
```
CacheInfoMXBean getStatistics()
```
    Return cache statistics. The result is never null regardless of the settings Cache2kBuilder.enableJmx(boolean) or Cache2kBuilder.disableStatistics(boolean)
    
    Since:
    
    1.4

Interface Cache<K,V>

Method Summary

Method Detail

getName

get

getEntry

prefetch

prefetchAll

peek

peekEntry

containsKey

put

computeIfAbsent

putIfAbsent

peekAndReplace

replace

replaceIfEquals

peekAndRemove

containsAndRemove

remove

removeIfEquals

removeAll

peekAndPut

expireAt

loadAll

reloadAll

invoke

invokeAll

getAll

peekAll

putAll

keys

entries

removeAll

clear

clearAndClose

close

getCacheManager

isClosed

toString

requestInterface

asMap

getStatistics