org.ehcache
Interface Cache<K,V>

Type Parameters:

K - the type of the keys used to access data within this cache

V - the type of the values held within this cache

All Superinterfaces:

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

All Known Subinterfaces:

PersistentUserManagedCache<K,V>, UserManagedCache<K,V>

All Known Implementing Classes:

Ehcache, PersistentUserManagedEhcache

public interface Cache<K,V>
extends java.lang.Iterable<Cache.Entry<K,V>>

Basic interface to a cache, defines all operational methods to create, access, update or delete mappings of key to value

Nested Class Summary

static interface

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

Method Summary

void	clear() Removes all mapping currently present in the Cache without invoking the CacheLoaderWriter or any registered CacheEventListener instances This is not an atomic operation and can potentially be very expensive
boolean	containsKey(K key) Checks whether a mapping for the given key is present, without retrieving the associated value
V	get(K key) Retrieve 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 keys.
CacheRuntimeConfiguration<K,V>	getRuntimeConfiguration() Exposes the CacheRuntimeConfiguration associated with this Cache instance.
void	put(K key, V value) Associates the provided value to the given key
void	putAll(java.util.Map<? extends K,? extends V> entries) Associates all the provided key:value pairs.
V	putIfAbsent(K key, V value) If the provided key is not associated with a value, then associate it with the provided value.
void	remove(K key) Removes the value, if any, associated with the provided key
boolean	remove(K key, V value) If the provided key is associated with the provided value then remove the entry.
void	removeAll(java.util.Set<? extends K> keys) Removes any associates for the given keys.
V	replace(K key, V value) If the provided key is associated with a value, then replace that value with the provided value.
boolean	replace(K key, V oldValue, V newValue) If the provided key is associated with oldValue, then replace that value with newValue.

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

get

V get(K key)
      throws CacheLoadingException

Retrieve the value currently mapped to the provided key

Parameters:

key - the key to query the value for

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 provided value to the given key

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 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

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

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 keys.

Parameters:

keys - keys to query for

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

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 underlying system of record.

removeAll

void removeAll(java.util.Set<? extends K> keys)
               throws BulkCacheWritingException

Removes any associates for the given keys.

Parameters:

keys - keys to remove values for

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 underlying system of record.

clear

void clear()

Removes all mapping currently present in the Cache 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

If the provided key is not associated with a value, then associate it with the provided value.

Parameters:

key - the key to be associated with

value - the value to associate

Returns:

the value that was associated with the key, or null if none

Throws:

java.lang.NullPointerException - if either key or value is null

CacheLoadingException - if the CacheLoaderWriter associated with this cache was invoked and threw an Exception while loading the value for the key

CacheWritingException - if the CacheLoaderWriter associated with this cache threw an Exception while writing the value for the given key to underlying system of record.

remove

boolean remove(K key,
               V value)
               throws CacheWritingException

If the provided key is associated with the provided value then remove the entry.

Parameters:

key - the key to remove

value - the value to check against

Returns:

true if the entry was removed

Throws:

java.lang.NullPointerException - if either key or value is null

CacheWritingException - if the CacheLoaderWriter associated with this cache threw an Exception while removing the given key:value mapping

replace

V replace(K key,
          V value)
          throws CacheLoadingException,
                 CacheWritingException

If the provided key is associated with a value, then replace that value with the provided value.

Parameters:

key - the key to be associated with

value - the value to associate

Returns:

the value that was associated with the key, or null if none

Throws:

java.lang.NullPointerException - if either key or value is null

CacheLoadingException - if the CacheLoaderWriter associated with this cache was invoked and threw an Exception while loading the value for the key

CacheWritingException - if the CacheLoaderWriter associated with this cache was invoked and threw an Exception while replacing value for given key on underlying system of record.

replace

boolean replace(K key,
                V oldValue,
                V newValue)
                throws CacheLoadingException,
                       CacheWritingException

If the provided key is associated with oldValue, then replace that value with newValue.

Parameters:

key - the key to be associated with

oldValue - the value to check against

newValue - the value to associate

Returns:

true if the value was replaced

Throws:

java.lang.NullPointerException - if any of the values, or the key is null

CacheLoadingException - if the CacheLoaderWriter associated with this cache was invoked and threw an Exception while loading the value for the key

CacheWritingException - if the CacheLoaderWriter associated with this cache was invoked and threw an Exception while replacing value for given key on underlying system of record.

getRuntimeConfiguration

CacheRuntimeConfiguration<K,V> getRuntimeConfiguration()

Exposes the CacheRuntimeConfiguration associated with this Cache instance.

Returns:

the configuration currently in use