|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
K
- the key type for the cacheV
- the value type for the cachepublic interface Cache<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:
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.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 | |
---|---|
static interface |
Cache.Entry<K,V>
A mapping of key to value held in a Cache . |
Method Summary | |
---|---|
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 |
---|
iterator |
Method Detail |
---|
V get(K key) throws CacheLoadingException
key
- the key, may not be null
null
if none
java.lang.NullPointerException
- if the provided key is null
CacheLoadingException
- if the CacheLoaderWriter
associated with this cache was
invoked and threw an Exception
void put(K key, V value) throws CacheWritingException
Cache
.
key
- the key, may not be null
value
- the value, may not be null
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.boolean containsKey(K key)
key
- the key, may not be null
true
if a mapping is present, false
otherwise
java.lang.NullPointerException
- if the provided key is null
void remove(K key) throws CacheWritingException
key
- the key to remove the value for, may not be null
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.java.util.Map<K,V> getAll(java.util.Set<? extends K> keys) throws BulkCacheLoadingException
keys
- keys to query for, may not contain null
null
if the key was not mapped
java.lang.NullPointerException
- if the Set
or any of the contained keys are null
.
BulkCacheLoadingException
- if loading some or all values failedvoid putAll(java.util.Map<? extends K,? extends V> entries) throws BulkCacheWritingException
entries
- key:value pairs to associate, keys or values may not be null
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.void removeAll(java.util.Set<? extends K> keys) throws BulkCacheWritingException
keys
- keys to remove values for, may not be null
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.void clear()
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.
V putIfAbsent(K key, V value) throws CacheLoadingException, CacheWritingException
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.
null
.
key
- key with which the specified value is to be associatedvalue
- value to be associated with the specified key
null
if no such mapping existed or the mapping was expired
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
boolean remove(K key, V value) throws CacheWritingException
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
.
key
- key with which the specified value is associatedvalue
- value expected to be removed
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.V replace(K key, V value) throws CacheLoadingException, CacheWritingException
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
.
key
- of the value to be replacedvalue
- the new value
null
if
no such mapping existed or the mapping was expired
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
boolean replace(K key, V oldValue, V newValue) throws CacheLoadingException, CacheWritingException
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
.
key
- key with which the specified value is associatedoldValue
- value expected to be associated with the specified keynewValue
- value to be associated with the specified key
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
CacheRuntimeConfiguration<K,V> getRuntimeConfiguration()
CacheRuntimeConfiguration
associated with this Cache instance.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |