com.cloudtran.coherence.llapi
Interface Persister


public interface Persister

This interface defines the class to be used to deal with persistence for LLAPI transactions. The methods

If you have no persistence (no databases or permanent storage for grid objects), you do not need to specify this class - it is not required. There is no default implementation, so no objects will be persisted if you do not specify the persister class.

To define the Persister class, set the configuration parameter ct.manager.llapi.persisterClass to the fully qualified class name of the persister.

CloudTran will instantiate a single object of this class to deal with all transactions, so all methods must be thread-safe.


Method Summary
 void doPersist(List<CohortEntryActionLL> persistableActions, long internalTxId, Runnable finishPersist)
          This method is called to persist the transaction.
 List<CohortEntryActionLL> doTransform(List<CohortEntryActionLL> inputActions)
          This method transforms a list of CohortEntryActions referencing grid objects, to a list of CohortEntryActions referencing persistable objects.
 Object getPrimaryKey(Object entity)
          Gets the primary key for the given entity.
 

Method Detail

doTransform

List<CohortEntryActionLL> doTransform(List<CohortEntryActionLL> inputActions)
                                      throws RowTransformException
This method transforms

Grid applications often store aggregate objects in the cache to reduce the number of network calls needed to retrieve information for a use case. If the application is going to a database with a normalised schema, the simplest and safest approach to writing the transformer is to convert the aggregate into individual objects that are equivalent to the data stores unit of storage - like rows in a database.

However, you can leave the object in its aggregated form after the transform if certain conditions are met:

In this case, the 'doTransform' method does not need to transform the inputActions list; it can simply return it.

The benefit of delaying the transform to persistable objects is that it will reduces the load on the isolator, which ensures that persistence from different managers across the grid do not hit the datasource in the wrong order. If you use the master object as a surrogate for all the objects as far as isolator is concerned, it reduces the traffic and processing load at the isolator.

Parameters:
inputActions - The list of CohortEntryActions referencing grid objects.
Returns:
The list of CohortEntryActions referencing persistable objects. The objects referenced by these actions must have a primary key, i.e. return a non-null value to getPrimaryKey(object).
Throws:
TransactionExceptionParameterOrUsageError - if a referenced object does not have a primary key.
RowTransformException

doPersist

void doPersist(List<CohortEntryActionLL> persistableActions,
               long internalTxId,
               Runnable finishPersist)
This method is called to persist the transaction.

When this method is called, the transaction will be at least in committing state and persistence must succeed. This means you must retry the persistence operation if there is a problem, such as the connection to the database is down.

Before calling this method, CloudTran ensures that there are no other transactions involving the objects referenced in 'persistableActions'. This means the doPersist() call occurs after the doTransform() call, sometimes by a considerable amount of time if the datastore is down.

The method is called synchronously with the transaction manager's commit operation but you should not hold up the commit operation - in the case of retries, you would not return to the caller for a long time. This means you should use a worker thread pool that is bound in size and services a queue; then doPersist can put the object on the queue and return immediately.

doPersist must be idempotent, because after failover or repartitioning this method can be called again on another cache node. This means, for example, database inserts may fail on the second execution because the object already exists, but doPersist must treat this as a successful operation (because it was done before).

The TransactionInfoForPersistor contains the list of CohortEntryActions which hold the information about each object to be persisted as well as the action required (CREATE, DELETE, UPDATE). In the case of an aggregate, you can use the CohortEntryActionLL.previousValue and compare it with the newValueObject to determine which of the component objects has changed and how.

Parameters:
persistableActions - The list of CohortEntryActions referencing persistable objects, as returned by doTransform()
internalTxId - The internal transaction Id, for use in error messages
finishPersist - You *must* call the run() method on this object when you have finished the persistence. This allows cloudtran to complete the transaction. Until you do this, resources will be held in the transaction manager.

getPrimaryKey

Object getPrimaryKey(Object entity)
Gets the primary key for the given entity.

Parameters:
entity -
Returns:
null if there is no primary key, otherwise the primary key object