org.ehcache.core.spi.store

Interface Store<K,V>

Type Parameters:

K - the key type

V - the value type

All Superinterfaces:

ConfigurationChangeSupport

All Known Subinterfaces:

AuthoritativeTier<K,V>, WrapperStore<K,V>

public interface Store<K,V>
extends ConfigurationChangeSupport

The Store interface represents the backing storage of a Cache. It abstracts the support for multiple tiers, eventing, eviction and expiry.

It maps key of type K to value holder which contains value of type V and associated metadata.

Store implementations must not handle null keys or values.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Store.Configuration<K,V> The basic configuration for a Store.
static interface	Store.Iterator<T> An iterator over a Store.
static interface	Store.Provider The Service used to create Stores.
static class	Store.PutStatus Put operation status
static class	Store.RemoveStatus Conditional Remove operation status
static class	Store.ReplaceStatus Conditional Replace operation status
static interface	Store.ValueHolder<V> Holds both a value, and all the metadata associated with a mapping in a Store.

Method Summary

Modifier and Type	Method and Description
java.util.Map<K,Store.ValueHolder<V>>	bulkCompute(java.util.Set<? extends K> keys, java.util.function.Function<java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>>,java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>>> remappingFunction) Compute a value for every key passed in the Set keys argument, using the remappingFunction to compute the value.
java.util.Map<K,Store.ValueHolder<V>>	bulkCompute(java.util.Set<? extends K> keys, java.util.function.Function<java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>>,java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>>> remappingFunction, java.util.function.Supplier<java.lang.Boolean> replaceEqual) Compute a value for every key passed in the Set keys argument, using the remappingFunction to compute the value.
java.util.Map<K,Store.ValueHolder<V>>	bulkComputeIfAbsent(java.util.Set<? extends K> keys, java.util.function.Function<java.lang.Iterable<? extends K>,java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>>> mappingFunction) Compute a value for every key passed in the Set keys argument using the mappingFunction to compute the value.
void	clear() Removes all of the mappings from this Store.
Store.ValueHolder<V>	computeAndGet(K key, java.util.function.BiFunction<? super K,? super V,? extends V> mappingFunction, java.util.function.Supplier<java.lang.Boolean> replaceEqual, java.util.function.Supplier<java.lang.Boolean> invokeWriter) Compute the value for the given key by invoking the given function to produce the value.
Store.ValueHolder<V>	computeIfAbsent(K key, java.util.function.Function<? super K,? extends V> mappingFunction) Compute the value for the given key (only if absent or expired) by invoking the given function to produce the value.
boolean	containsKey(K key) Returns true if this store contains the specified key and the entry is not expired.
Store.ValueHolder<V>	get(K key) Returns the ValueHolder to which the specified key is mapped, or null if this store contains no mapping for the key or if it was evicted (or became expired) since it was initially installed.
Store.ValueHolder<V>	getAndCompute(K key, java.util.function.BiFunction<? super K,? super V,? extends V> mappingFunction) Compute the value for the given key by invoking the given function to produce the value.
default Store.ValueHolder<V>	getAndPut(K key, V value) Maps the specified key to the specified value in this store.
default Store.ValueHolder<V>	getAndRemove(K key) Removes the key (and its corresponding value) from this store.
StoreEventSource<K,V>	getStoreEventSource() Exposes the Store eventing system to allow configuration and registration of listeners.
Store.Iterator<Cache.Entry<K,Store.ValueHolder<V>>>	iterator() Returns an iterator over the elements in this store.
Store.PutStatus	put(K key, V value) Maps the specified key to the specified value in this store.
Store.ValueHolder<V>	putIfAbsent(K key, V value, java.util.function.Consumer<java.lang.Boolean> put) Maps the specified key to the specified value in this store, unless a non-expired mapping already exists.
boolean	remove(K key) Removes the key (and its corresponding value) from this store.
Store.RemoveStatus	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.
Store.ValueHolder<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.
Store.ReplaceStatus	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 org.ehcache.core.spi.store.ConfigurationChangeSupport

getConfigurationChangeListeners

Method Detail

get

Store.ValueHolder<V> get(K key)
                  throws StoreAccessException

Returns the ValueHolder to which the specified key is mapped, or null if this store contains no mapping for the key or if it was evicted (or became expired) since it was initially installed.

More formally, if this store contains a non-expired mapping from a key k to a ValueHolder v such that key.equals(k), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

The key cannot be null.

Parameters:

key - the key of the mapping to lookup

Returns:

the value mapped to this key or null if no mapping exists or is expired

Throws:

java.lang.NullPointerException - if the argument is null

java.lang.ClassCastException - if the specified key is not an instance of K

StoreAccessException - if the mapping can't be retrieved

containsKey

boolean containsKey(K key)
             throws StoreAccessException

Returns true if this store contains the specified key and the entry is not expired.

More formally, returns true if and only if this store contains a key k such that (o.equals(k)).

The key cannot be null.

Parameters:

key - key whose presence in this store is to be tested

Returns:

true if this store contains the specified non-expired element, false otherwise

Throws:

java.lang.NullPointerException - if the argument is null

java.lang.ClassCastException - if the specified key is not an instance of K

StoreAccessException - if the presence can't be tested for

put

Store.PutStatus put(K key,
                    V value)
             throws StoreAccessException

Maps the specified key to the specified value in this store. Neither the key nor the value can be null.

The ValueHolder 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:

Store.PutStatus based on the result of the operation in store

Throws:

java.lang.NullPointerException - if any of the arguments is null

java.lang.ClassCastException - if the specified key or value are not of the correct types (K or V)

StoreAccessException - if the mapping can't be installed

getAndPut

default Store.ValueHolder<V> getAndPut(K key,
                                       V value)
                                throws StoreAccessException

Maps the specified key to the specified value in this store. 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 previously associated value

Throws:

java.lang.NullPointerException - if any of the arguments is null

java.lang.ClassCastException - if the specified key or value are not of the correct types (K or V)

StoreAccessException - if the mapping can't be installed

putIfAbsent

Store.ValueHolder<V> putIfAbsent(K key,
                                 V value,
                                 java.util.function.Consumer<java.lang.Boolean> put)
                          throws StoreAccessException

Maps the specified key to the specified value in this store, unless a non-expired mapping already exists.

This is equivalent to

   if (!store.containsKey(key))
       store.put(key, value);
       return null;
   else
       return store.get(key);
 

except that the action is performed atomically.

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

put - lambda to be consumed if value has been put

Returns:

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

java.lang.ClassCastException - if the specified key or value are not of the correct types (K or V)

StoreAccessException - if the mapping can't be installed

See Also:

replace(Object, Object)

remove

boolean remove(K key)
        throws StoreAccessException

Removes the key (and its corresponding value) from this store. This method does nothing if the key is not mapped.

The key cannot be null.

Parameters:

key - the key that needs to be removed

Returns:

true if the mapping existed and was successfully removed, false otherwise

Throws:

java.lang.NullPointerException - if the specified key is null

java.lang.NullPointerException - if the argument is null

StoreAccessException - if the mapping can't be removed

getAndRemove

default Store.ValueHolder<V> getAndRemove(K key)
                                   throws StoreAccessException

Removes the key (and its corresponding value) from this store. This method does nothing if the key is not mapped.

The key cannot be null.

Parameters:

key - the key that needs to be removed

Returns:

the previously associated value

Throws:

java.lang.NullPointerException - if the specified key is null

java.lang.NullPointerException - if the argument is null

StoreAccessException - if the mapping can't be removed

remove

Store.RemoveStatus remove(K key,
                          V value)
                   throws StoreAccessException

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 (store.containsKey(key)) {
     if (store.get(key).equals(value)) {
       store.remove(key);
       return REMOVED;
     } else return KEY_PRESENT;
   } else return KEY_MISSING;

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 associated with the specified key

Returns:

Store.RemoveStatus based on the result of the remove operation in store

Throws:

java.lang.ClassCastException - if the specified key or value are not of the correct types (K or V)

java.lang.NullPointerException - if any of the arguments is null

StoreAccessException - if the mapping can't be removed

replace

Store.ValueHolder<V> replace(K key,
                             V value)
                      throws StoreAccessException

Replaces the entry for a key only if currently mapped to some value and the entry is not expired.

This is equivalent to

   ValueHolder<V> oldValue = store.get(key);
   if (oldValue != null) {
     store.put(key, value);
   }
   return oldValue; 

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

value - value expected to be associated with the specified key

Returns:

the ValueHolder to which the specified key was previously mapped, or null if no such mapping existed

Throws:

java.lang.ClassCastException - if the specified key or value are not of the correct types (K or V)

java.lang.NullPointerException - if any of the arguments is null

StoreAccessException - if the mapping can't be replaced

replace

Store.ReplaceStatus replace(K key,
                            V oldValue,
                            V newValue)
                     throws StoreAccessException

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 (store.containsKey(key)) {
     if (store.get(key).equals(oldValue)) {
       store.put(key, newValue);
       return HIT;
     } else {
       return MISS_PRESENT;
     }
   } else {
     return MISS_NOT_PRESENT;
   }

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:

Store.ReplaceStatus based on the result of the replace operation in store

Throws:

java.lang.ClassCastException - if the specified key or values are not of the correct types (K or V)

java.lang.NullPointerException - if any of the arguments is null

StoreAccessException - if the mapping can't be replaced

clear

void clear()
    throws StoreAccessException

Removes all of the mappings from this Store.

This method provides no guarantee of atomicity.

Throws:

StoreAccessException - if the store couldn't be partially or entirely be cleared.

getStoreEventSource

StoreEventSource<K,V> getStoreEventSource()

Exposes the Store eventing system to allow configuration and registration of listeners.

Returns:

the StoreEventSource of this Store

iterator

Store.Iterator<Cache.Entry<K,Store.ValueHolder<V>>> iterator()

Returns an iterator over the elements in this store.

The elements are returned in no particular order.

Returns:

an iterator over the mappings in this Store

getAndCompute

Store.ValueHolder<V> getAndCompute(K key,
                                   java.util.function.BiFunction<? super K,? super V,? extends V> mappingFunction)
                            throws StoreAccessException

Compute the value for the given key by invoking the given function to produce the value.

The function will be supplied with the key and existing value (or null if no entry exists) as parameters. The function should return the desired new value for the entry or null to remove the entry. If the function throws an unchecked exception the Store will not be modified and a StoreAccessException will be thrown.

This is equivalent to

   V oldValue = store.get(key;
   V newValue = mappingFunction.apply(key, oldValue);
   if (newValue != null) {
     store.put(key, newValue);
   } else {
     store.remove(key);
   }
   return oldValue;
 

except that the action is performed atomically. Neither the key nor the function can be null

Parameters:

key - the key to update the mapping for

mappingFunction - the function that will produce the new value.

Returns:

the existing value associated with the key or null if none

Throws:

java.lang.ClassCastException - if the specified key is not of the correct type K

java.lang.NullPointerException - if any of the arguments is null

StoreAccessException - if the mapping can't be changed

computeAndGet

Store.ValueHolder<V> computeAndGet(K key,
                                   java.util.function.BiFunction<? super K,? super V,? extends V> mappingFunction,
                                   java.util.function.Supplier<java.lang.Boolean> replaceEqual,
                                   java.util.function.Supplier<java.lang.Boolean> invokeWriter)
                            throws StoreAccessException

Compute the value for the given key by invoking the given function to produce the value.

The mappingFunction will be supplied with the key and existing value (or null if no entry exists) as parameters. The mappingFunction should return the desired new value for the entry or null to remove the entry.

The replaceEqual function will be invoked if the mappingFunction returns a value that is equal to the existing value. If the replaceEqual function returns false then the existing mapping will not be replaced and will have its metadata updated.

If either function throws an unchecked exception the Store will not be modified and a StoreAccessException will be thrown.

This is equivalent to

   V oldValue = store.get(key);
   V newValue = mappingFunction.apply(key, oldValue);
   if (newValue != null) {
     if (!newValue.equals(oldValue) || replaceEqual.apply()) {
       store.put(key, newValue);
     }
   } else {
     store.remove(key);
   }
   return newValue;
 

except that the action is performed atomically.

Neither the key nor the functions can be null

Parameters:

key - the key to operate on

mappingFunction - the function that will produce the new value.

replaceEqual - indicates if an equal value replaces the existing one

invokeWriter - indicates if the writer should be invoked

Returns:

the new value associated with the key or null if none

Throws:

java.lang.ClassCastException - if the specified key is not of the correct type K

java.lang.NullPointerException - if any of the arguments is null

StoreAccessException - if the mapping can't be changed

computeIfAbsent

Store.ValueHolder<V> computeIfAbsent(K key,
                                     java.util.function.Function<? super K,? extends V> mappingFunction)
                              throws StoreAccessException

Compute the value for the given key (only if absent or expired) by invoking the given function to produce the value.

The function will be supplied with the key only if no mapping exists. The function should return the desired new value for the entry. null will result in a no-op. If the function throws an unchecked exception the Store will not be modified and a StoreAccessException will be thrown.

This is equivalent to

   if (!store.containsKey(key)) {
     V newValue = mappingFunction.apply(key);
     if (newValue != null) {
       store.put(key, newValue);
     }
     return newValue;
   }
   return store.get(key);
 

except that the action is performed atomically.

Neither the key nor the function can be null

Parameters:

key - the key to operate on

mappingFunction - the function that will produce the value.

Returns:

the new value associated with the key or null if none

Throws:

java.lang.ClassCastException - If the specified key is not of the correct type (K) or if the function returns a value that is not of type (V)

java.lang.NullPointerException - if any of the arguments is null

StoreAccessException - if the mapping can't be changed

bulkCompute

java.util.Map<K,Store.ValueHolder<V>> bulkCompute(java.util.Set<? extends K> keys,
                                                  java.util.function.Function<java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>>,java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>>> remappingFunction)
                                           throws StoreAccessException

Compute a value for every key passed in the Set keys argument, using the remappingFunction to compute the value.

The function gets an Iterable of Map.Entry key/value pairs, where each entry's value is its currently stored value, or null if nothing is stored under the key. It is expected that the function returns an Iterable of Map.Entry key/value pairs containing an entry for each key that was passed to it. This returned Iterable should also iterate in the same order as the input Iterable. If an entry's value is null, its mapping will be removed from the store.

Note that the remapping function can be invoked multiple times with key subsets but that it will never the see the same key in different invocations.

Behaviour is equivalent to compute invocations in an external loop. There is no cross key atomicity guarantee / requirement. Implementations may provide coarser grained guarantees.

This is equivalent to calling bulkCompute(Set, Function, Supplier) with a "replaceEquals" function that returns true

Parameters:

keys - the set of keys on which to compute values

remappingFunction - the function that generates new values

Returns:

a Map of key/value pairs for each key in keys to the value computed.

Throws:

java.lang.ClassCastException - if the specified key(s) are not of the correct type (K). Also thrown if the given function produces entries with either incorrect key or value types

java.lang.NullPointerException - if any of the arguments is null

StoreAccessException - if mappings can't be changed

bulkCompute

java.util.Map<K,Store.ValueHolder<V>> bulkCompute(java.util.Set<? extends K> keys,
                                                  java.util.function.Function<java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>>,java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>>> remappingFunction,
                                                  java.util.function.Supplier<java.lang.Boolean> replaceEqual)
                                           throws StoreAccessException

Compute a value for every key passed in the Set keys argument, using the remappingFunction to compute the value.

The function gets an Iterable of Map.Entry key/value pairs, where each entry's value is its currently stored value, or null if nothing is stored under the key. It is expected that the function returns an Iterable of Map.Entry key/value pairs containing an entry for each key that was passed to it. This returned Iterable should also iterate in the same order as the input Iterable. If an entry's value is null, its mapping will be removed from the store.

Note that the remapping function can be invoked multiple times with key subsets but that it will never the see the same key in different invocations.

Behaviour is equivalent to compute invocations in an external loop. There is no cross key atomicity guarantee / requirement. Implementations may provide coarser grained guarantees.

Parameters:

keys - the set of keys on which to compute values

remappingFunction - the function that generates new values

replaceEqual - If the existing value in the store is Object.equals(Object) to the value returned from the mappingFunction this function will be invoked. If this function returns Boolean.FALSE then the existing entry in the store will not be replaced with a new entry and the existing entry will have its access time updated

Returns:

a Map of key/value pairs for each key in keys to the value computed.

Throws:

java.lang.ClassCastException - if the specified key(s) are not of the correct type (K). Also thrown if the given function produces entries with either incorrect key or value types

java.lang.NullPointerException - if any of the arguments is null

StoreAccessException - if mappings can't be changed

bulkComputeIfAbsent

java.util.Map<K,Store.ValueHolder<V>> bulkComputeIfAbsent(java.util.Set<? extends K> keys,
                                                          java.util.function.Function<java.lang.Iterable<? extends K>,java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>>> mappingFunction)
                                                   throws StoreAccessException

Compute a value for every key passed in the Set keys argument using the mappingFunction to compute the value.

The function gets an Iterable of Map.Entry key/value pairs, where each entry's value is its currently stored value for each key that is not mapped in the store. It is expected that the function returns an Iterable of Map.Entry key/value pairs containing an entry for each key that was passed to it. This returned Iterable should also iterate in the same order as the input Iterable.

The function may be called multiple times per bulkComputeIfAbsent call, depending on how the store wants or does not want to batch computations.

Note: This method guarantees atomicity of computations for each individual key in keys. Implementations may choose to provide coarser grained atomicity.

Parameters:

keys - the keys to compute a new value for, if they're not in the store.

mappingFunction - the function that generates new values.

Returns:

a Map of key/value pairs for each key in keys to the previously missing value.

Throws:

java.lang.ClassCastException - if the specified key(s) are not of the correct type (K). Also thrown if the given function produces entries with either incorrect key or value types

StoreAccessException - when a failure occurs when accessing the store