org.apache.ignite.cache.store

## Interface CacheStore<K,V>

All Superinterfaces:
  javax.cache.integration.CacheLoader<K,V>, javax.cache.integration.CacheWriter<K,V>

All Known Implementing Classes:
  CacheAbstractJdbcStore, CacheJdbcBlobStore, CacheJdbcPojoStore, CacheLoadOnlyStoreAdapter, CacheStoreAdapter, CacheStoreBalancingWrapper, GridCacheWriteBehindStore

    public interface CacheStore<K,V>
    extends javax.cache.integration.CacheLoader<K,V>, javax.cache.integration.CacheWriter<K,V>

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

`CacheStoreAdapter` provides default implementation for bulk operations, such as `CacheLoader.loadAll(Iterable)`, `CacheWriter.writeAll(Collection)`, and `CacheWriter.deleteAll(Collection)` by sequentially calling corresponding `CacheLoader.load(Object)`, `#write(Entry)`, and `CacheWriter.delete(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:

- `CacheHibernateBlobStore`
- `CacheJdbcBlobStore`

All transactional operations of this API are provided with ongoing `Transaction`, if any. 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);
     }

# Working With Portable Objects

When portables are enabled for cache by setting `org.apache.ignite.configuration.CacheConfiguration#isPortableEnabled()` to `true`), all portable keys and values are converted to instances of `PortableObject`. Therefore, all cache store methods will take parameters in portable format. To avoid class cast exceptions, store must have signature compatible with portables. E.g., if you use `Integer` as a key and `Value` class as a value (which will be converted to portable format), cache store signature should be the following:

     public class PortableCacheStore implements GridCacheStore<Integer, GridPortableObject> {
         public void put(@Nullable GridCacheTx tx, Integer key, GridPortableObject val) throws IgniteCheckedException {
             ...
         }

         ...
     }

This behavior can be overridden by setting `org.apache.ignite.configuration.CacheConfiguration#setKeepPortableInStore(boolean)` flag value to `false`. In this case, Ignite will deserialize keys and values stored in portable format before they are passed to cache store, so that you can use the following cache store signature instead:

     public class ObjectsCacheStore implements GridCacheStore<Integer, Person> {
         public void put(@Nullable GridCacheTx tx, Integer key, Person val) throws GridException {
             ...
         }

         ...
     }

Note that while this can simplify store implementation in some cases, it will cause performance degradation due to additional serializations and deserializations of portable objects. You will also need to have key and value classes on all nodes since portables will be deserialized when store is invoked.

Note that only portable classes are converted to `PortableObject` format. Following types are stored in cache without changes and therefore should not affect cache store signature:

- All primitives (byte, int, ...) and there boxed versions (Byte, Integer, ...)
- Arrays of primitives (byte[], int[], ...)
- `String` and array of `String`s
- `UUID` and array of `UUID`s
- `Date` and array of `Date`s
- `Timestamp` and array of `Timestamp`s
- Enums and array of enums
- Maps, collections and array of objects (but objects inside them will still be converted if they are portable)

See Also:
  `CacheStoreSession`

### Method Summary

Methods
`void` `loadCache(IgniteBiInClosure<K,V> clo, Object... args)` Loads all values from underlying persistent storage.
`void` `txEnd(boolean commit)` Tells store to commit or rollback a transaction depending on the value of the `'commit'` parameter.

### Methods inherited from interface javax.cache.integration.CacheLoader

`load, loadAll`

### Methods inherited from interface javax.cache.integration.CacheWriter

`delete, deleteAll, write, writeAll`

### Method Detail

#### loadCache

    void loadCache(IgniteBiInClosure<K,V> clo,
                 @Nullable
                 Object... args)
                   throws javax.cache.integration.CacheLoaderException

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(org.apache.ignite.lang.IgniteBiPredicate, 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 `CacheStoreAdapter` does nothing.

For every loaded value method `IgniteBiInClosure.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(org.apache.ignite.lang.IgniteBiPredicate, long, Object...)` method.
Throws:
  `javax.cache.integration.CacheLoaderException` - If loading failed.

#### txEnd

    void txEnd(boolean commit)
               throws javax.cache.integration.CacheWriterException

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

Parameters:
  `commit` - `True` if transaction should commit, `false` for rollback.
Throws:
  `javax.cache.integration.CacheWriterException` - If commit or rollback failed. Note that commit failure in some cases may bring cache transaction into `TransactionState.UNKNOWN` which will consequently cause all transacted entries to be invalidated.

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.0.0-RC1
Release Date | : February 17 2015