org.gridgain.grid.cache.store

Interface GridCacheStore<K,V>

All Known Implementing Classes:

GridCacheJdbcBlobStore, GridCacheLoadOnlyStoreAdapter, GridCacheStoreAdapter, GridCacheWriteBehindStore

public interface GridCacheStore<K,V>

API for cache persistent storage for read-through and write-through behavior. Persistent store is configured via GridCacheConfiguration.getStore() configuration property. If not provided, values will be only kept in cache memory or swap storage without ever being persisted to a persistent storage.

GridCacheStoreAdapter provides default implementation for bulk operations, such as loadAll(GridCacheTx, Collection, GridBiInClosure), putAll(GridCacheTx, Map), and removeAll(GridCacheTx, Collection) by sequentially calling corresponding load(GridCacheTx, Object), put(GridCacheTx, Object, Object), and remove(GridCacheTx, Object) operations. Use this adapter whenever such behaviour is acceptable. However in many cases it maybe more preferable to take advantage of database batch update functionality, and therefore default adapter implementation may not be the best option.

Provided implementations may be used for test purposes:

• GridCacheHibernateBlobStore
• GridCacheJdbcBlobStore

All transactional operations of this API are provided with ongoing GridCacheTx, if any. As transaction is GridMetadataAware, you can attach any metadata to it, e.g. to recognize if several operations belong to the same transaction or not. Here is an example of how attach a JDBC connection as transaction metadata:

 Connection conn = tx.meta("some.name");

 if (conn == null) {
     conn = ...; // Get JDBC connection.

     // Store connection in transaction metadata, so it can be accessed
     // for other operations on the same transaction.
     tx.addMeta("some.name", conn);
 }
 

Method Summary

Methods

Modifier and Type	Method and Description
V	load(GridCacheTx tx, K key) Loads value for the key from underlying persistent storage.
void	loadAll(GridCacheTx tx, Collection<? extends K> keys, GridBiInClosure<K,V> c) Loads all values for given keys and passes every value to the provided closure.
void	loadCache(GridBiInClosure<K,V> clo, Object... args) Loads all values from underlying persistent storage.
void	put(GridCacheTx tx, K key, V val) Stores a given value in persistent storage.
void	putAll(GridCacheTx tx, Map<? extends K,? extends V> map) Stores given key value pairs in persistent storage.
void	remove(GridCacheTx tx, K key) Removes the value identified by given key from persistent storage.
void	removeAll(GridCacheTx tx, Collection<? extends K> keys) Removes all vales identified by given keys from persistent storage.
void	txEnd(GridCacheTx tx, boolean commit) Tells store to commit or rollback a transaction depending on the value of the 'commit' parameter.

Method Detail

load

@Nullable
V load(@Nullable
              GridCacheTx tx,
              K key)
       throws GridException

Loads value for the key from underlying persistent storage.

Parameters:

tx - Cache transaction.

key - Key to load.

Returns:

Loaded value or null if value was not found.

Throws:

GridException - If load failed.

loadCache

void loadCache(GridBiInClosure<K,V> clo,
             @Nullable
             Object... args)
               throws GridException

Loads all values from underlying persistent storage. Note that keys are not passed, so it is up to implementation to figure out what to load. This method is called whenever GridCache.loadCache(GridBiPredicate, long, Object...) method is invoked which is usually to preload the cache from persistent storage.

This method is optional, and cache implementation does not depend on this method to do anything. Default implementation of this method in GridCacheStoreAdapter does nothing.

For every loaded value method GridBiInClosure.apply(Object, Object) should be called on the passed in closure. The closure will then make sure that the loaded value is stored in cache.

Parameters:

clo - Closure for loaded values.

args - Arguments passes into GridCache.loadCache(GridBiPredicate, long, Object...) method.

Throws:

GridException - If loading failed.

loadAll

void loadAll(@Nullable
           GridCacheTx tx,
           Collection<? extends K> keys,
           GridBiInClosure<K,V> c)
             throws GridException

Loads all values for given keys and passes every value to the provided closure.

For every loaded value method GridInClosure.apply(Object) should be called on the passed in closure. The closure will then make sure that the loaded value is stored in cache.

Parameters:

tx - Cache transaction.

keys - Collection of keys to load.

c - Closure to call for every loaded element.

Throws:

GridException - If load failed.

put

void put(@Nullable
       GridCacheTx tx,
       K key,
       V val)
         throws GridException

Stores a given value in persistent storage. Note that cache transaction is implicitly created even for a single put. However, if write-behind is configured for a particular cache, transaction object passed in the cache store will be always null.

Parameters:

tx - Cache transaction, if write-behind is not enabled, null otherwise.

key - Key to put.

val - Value to put.

Throws:

GridException - If put failed.

putAll

void putAll(@Nullable
          GridCacheTx tx,
          Map<? extends K,? extends V> map)
            throws GridException

Stores given key value pairs in persistent storage. Note that cache transaction is implicitly created even for a single put. However, if write-behind is configured for a particular cache, transaction object passed in the cache store will be always null.

Parameters:

tx - Cache transaction, if write-behind is not enabled, null otherwise.

map - Values to store.

Throws:

GridException - If store failed.

remove

void remove(@Nullable
          GridCacheTx tx,
          K key)
            throws GridException

Removes the value identified by given key from persistent storage. Note that cache transaction is implicitly created even for a single put. However, if write-behind is configured for a particular cache, transaction object passed in the cache store will be always null.

Parameters:

tx - Cache transaction, if write-behind is not enabled, null otherwise.

key - Key to remove.

Throws:

GridException - If remove failed.

removeAll

void removeAll(@Nullable
             GridCacheTx tx,
             Collection<? extends K> keys)
               throws GridException

Removes all vales identified by given keys from persistent storage. Note that cache transaction is implicitly created even for a single put. However, if write-behind is configured for a particular cache, transaction object passed in the cache store will be always null.

Parameters:

tx - Cache transaction, if write-behind is not enabled, null otherwise.

keys - Keys to remove.

Throws:

GridException - If remove failed.

txEnd

void txEnd(GridCacheTx tx,
         boolean commit)
           throws GridException

Tells store to commit or rollback a transaction depending on the value of the 'commit' parameter.

Note that if explicit transactions are not used in code, then it is possible to commit or rollback transactions directly in 'put(..)', or 'remove(..)' methods. In that case, this method should be left empty (GridCacheStoreAdapter provides empty implementation of this method).

Parameters:

tx - Cache transaction being ended.

commit - True if transaction should commit, false for rollback.

Throws:

GridException - If commit or rollback failed. Note that commit failure in some cases may bring cache transaction into GridCacheTxState.UNKNOWN which will consequently cause all transacted entries to be invalidated.