org.ehcache.spi.cache
Interface Store<K,V>

All Superinterfaces:

ConfigurationChangeSupport

All Known Subinterfaces:

AuthoritativeTier<K,V>

All Known Implementing Classes:

AbstractOffHeapStore, CacheStore, OffHeapDiskStore, OffHeapStore, OnHeapStore

public interface Store<K,V>
extends ConfigurationChangeSupport

The Service Provider Interface is what a Cache instance requires to be able to store Cache entries (i.e. mappings of key to value, including all metadata). It is basically a ConcurrentMap with built in eviction/expiration. Possibly, it represents a view on data held on some persistent and/or remote storage.

Nested Class Summary

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.PersistentStoreConfiguration<K,V,T>
static interface	Store.Provider The Service used to create Stores.
static interface	Store.ValueHolder<V> Holds both a value, and all the metadata associated with a mapping in a Store.

Method Summary

java.util.Map<K,Store.ValueHolder<V>>	bulkCompute(java.util.Set<? extends K> keys, 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, 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, NullaryFunction<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, 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 map.
Store.ValueHolder<V>	compute(K key, BiFunction<? super K,? super V,? extends V> mappingFunction) Compute the value for the given key by invoking the given function to produce the value.
Store.ValueHolder<V>	compute(K key, BiFunction<? super K,? super V,? extends V> mappingFunction, NullaryFunction<java.lang.Boolean> replaceEqual) Compute the value for the given key by invoking the given function to produce the value.
Store.ValueHolder<V>	computeIfAbsent(K key, 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.
Store.ValueHolder<V>	computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction) Compute the value for the given key (only if present and non-expired) by invoking the given function to produce the value.
Store.ValueHolder<V>	computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction, NullaryFunction<java.lang.Boolean> replaceEqual) Compute the value for the given key (only if present and non-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.
void	disableStoreEventNotifications() Disables store event notifications.
void	enableStoreEventNotifications(StoreEventListener<K,V> listener) Enables notifications for store-initiated events, i.e.
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.Iterator<Cache.Entry<K,Store.ValueHolder<V>>>	iterator() Returns an iterator over the elements in this store.
void	put(K key, V value) Maps the specified key to the specified value in this store.
Store.ValueHolder<V>	putIfAbsent(K key, V value) Maps the specified key to the specified value in this store, unless a non-expired mapping already exists.
void	remove(K key) Removes the key (and its corresponding value) from this store.
boolean	remove(K key, V value) Removes the entry for a key only if currently mapped to a given value and the entry is not expired This is equivalent to
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.
boolean	replace(K key, V oldValue, V newValue) Replaces the entry for a key only if currently mapped to a given value and the entry is not expired.

Methods inherited from interface org.ehcache.spi.cache.ConfigurationChangeSupport

getConfigurationChangeListeners

Method Detail

get

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

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

Throws:

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

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

CacheAccessException - if the mapping can't be retrieved

containsKey

boolean containsKey(K key)
                    throws CacheAccessException

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

Parameters:

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

Returns:

true if this store contains the specified non-expired element

Throws:

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

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

CacheAccessException - if the presence can't be tested for

put

void put(K key,
         V value)
         throws CacheAccessException

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.

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

Throws:

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

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

CacheAccessException - if the mapping can't be installed

putIfAbsent

Store.ValueHolder<V> putIfAbsent(K key,
                                 V value)
                                 throws CacheAccessException

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

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 the specified key or value is null

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

CacheAccessException - if the mapping can't be installed

remove

void remove(K key)
            throws CacheAccessException

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

Parameters:

key - the key that needs to be removed

Throws:

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

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

CacheAccessException - if the mapping can't be removed

remove

boolean remove(K key,
               V value)
               throws CacheAccessException

Removes the entry for a key only if currently mapped to a given value and the entry is not expired This is equivalent to

   if (store.containsKey(key) && store.get(key).equals(value)) {
       store.remove(key);
       return true;
   } else return false;

except that the action is performed atomically.

Parameters:

key - key with which the specified value is associated

value - value expected to be associated with the specified key

Returns:

true if the value was removed

Throws:

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

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

CacheAccessException - if the mapping can't be removed

replace

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

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 = store.get(key);
   if (oldValue != null) {
     map.put(key, value);
   }
   return oldValue; 

except that the action is performed atomically.

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 the specified key or value is null

CacheAccessException - if the mapping can't be replaced

replace

boolean replace(K key,
                V oldValue,
                V newValue)
                throws CacheAccessException

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

   if (store.containsKey(key) && store.get(key).equals(oldValue)) {
       store.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:

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

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

CacheAccessException - if the mapping can't be replaced

clear

void clear()
           throws CacheAccessException

Removes all of the mappings from this map. This method provides no guarantee in terms of atomicity.

Throws:

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

enableStoreEventNotifications

void enableStoreEventNotifications(StoreEventListener<K,V> listener)

Enables notifications for store-initiated events, i.e. eviction and expiration.

Parameters:

listener - listener to notify

disableStoreEventNotifications

void disableStoreEventNotifications()

Disables store event notifications.

iterator

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

Returns an iterator over the elements in this store. The elements are returned in no particular order (unless this set is an instance of some class that provides a guarantee).

Returns:

an iterator over the mappings in this set

Throws:

CacheAccessException

compute

Store.ValueHolder<V> compute(K key,
                             BiFunction<? super K,? super V,? extends V> mappingFunction)
                             throws CacheAccessException

Compute the value for the given key by invoking the given function to produce the value. The entire operation is performed atomically. This is equivalent to calling compute(Object, BiFunction, NullaryFunction) with a "replaceEquals" function that returns Boolean.TRUE

Throws:

CacheAccessException

compute

Store.ValueHolder<V> compute(K key,
                             BiFunction<? super K,? super V,? extends V> mappingFunction,
                             NullaryFunction<java.lang.Boolean> replaceEqual)
                             throws CacheAccessException

Compute the value for the given key by invoking the given function to produce the value. The entire operation is performed atomically.

Parameters:

key - the key to operate on

mappingFunction - the function that will 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 method throws an unchecked exception the Store will not be modified (the caller will receive the exception)

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:

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)

CacheAccessException

computeIfAbsent

Store.ValueHolder<V> computeIfAbsent(K key,
                                     Function<? super K,? extends V> mappingFunction)
                                     throws CacheAccessException

Compute the value for the given key (only if absent or expired) by invoking the given function to produce the value. The entire operation is performed atomically.

Parameters:

key - the key to operate on

mappingFunction - the function that will produce the value. The function will be supplied with the key as a parameter. The function return the desired new value for the entry or null to remove the entry. If the method throws an unchecked exception the Store will not be modified (the caller will receive the exception)

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)

CacheAccessException

computeIfPresent

Store.ValueHolder<V> computeIfPresent(K key,
                                      BiFunction<? super K,? super V,? extends V> remappingFunction)
                                      throws CacheAccessException

Compute the value for the given key (only if present and non-expired) by invoking the given function to produce the value. The entire operation is performed atomically.

This is equivalent to calling computeIfPresent(Object, BiFunction, NullaryFunction) with a "replaceEquals" function that returns Boolean.TRUE

Throws:

CacheAccessException

computeIfPresent

Store.ValueHolder<V> computeIfPresent(K key,
                                      BiFunction<? super K,? super V,? extends V> remappingFunction,
                                      NullaryFunction<java.lang.Boolean> replaceEqual)
                                      throws CacheAccessException

Compute the value for the given key (only if present and non-expired) by invoking the given function to produce the value. The entire operation is performed atomically.

Parameters:

key - the key to operate on

remappingFunction - the function that will produce the value. The function will be supplied with the key and existing value as parameters. The function should return the desired new value for the entry or null to remove the entry. If the method throws an unchecked exception the Store will not be modified (the caller will receive the exception)

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:

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)

CacheAccessException

bulkCompute

java.util.Map<K,Store.ValueHolder<V>> bulkCompute(java.util.Set<? extends K> keys,
                                                  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 CacheAccessException

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

This is equivalent to calling bulkCompute(Set, Function, NullaryFunction) with a "replaceEquals" function that returns Boolean.TRUE

Throws:

CacheAccessException

bulkCompute

java.util.Map<K,Store.ValueHolder<V>> bulkCompute(java.util.Set<? extends K> keys,
                                                  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,
                                                  NullaryFunction<java.lang.Boolean> replaceEqual)
                                                  throws CacheAccessException

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.

The function may be called multiple times per bulkCompute 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.

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

CacheAccessException

bulkComputeIfAbsent

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

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

CacheAccessException