com.cloudtran.api
Interface ITxBufferManager


public interface ITxBufferManager


Method Summary
 void abort(CTxDefinition ctxDefinition)
          Aborts the transaction from the client.
 com.cloudtran.shared.TransactionInstruction abortIfActive(long internalTxId)
          This is internal to CloudTran implementation: clients of the CloudTran platform shouldn't use it.
 void commit(CTxDefinition ctxDefinition)
          Commits the transaction from the client.
 long getNanoTime()
          getNanoTime() is used to synchronise our watches.
 long getNanoTimeToMillisAdjustment()
          getNanoTimeMillisAdjustment() is used to synchronise our watches.
 com.cloudtran.shared.TransactionInstruction getTransactionStatus(long internalTxId)
           
 boolean isOpenForBusiness()
          The "Open for Business" flag is used by both clients and CloudTran internally.
 CTxDefinition start(CTxDefinition ctxDefinition)
          Start a new distributed transaction.
 void txAbortedByCohort(CTxDefinition ctxDefinition)
          This is internal to CloudTran implementation: clients of the CloudTran platform shouldn't use it.
 void waitForAllComplete()
          wait for all transactions to be completed.
 com.cloudtran.shared.CTxInfo whatHappenedTo(long internalTxId)
          Call this method to find out what happened to a transaction based on its internal transaction id 'internalTxId'.
 byte whatHappenedTo(String name)
          Call this method to find out what happened to a transaction based on its business transaction named with the name parameter.
 

Method Detail

start

CTxDefinition start(CTxDefinition ctxDefinition)
                    throws TransactionExceptionRetriable,
                           TransactionExceptionNameUsedBefore
Start a new distributed transaction. This is called a client application, or either directly from a client or via a service in the grid. In particular, the CloudTran ORM starts transactions automatically for simple entity tree saves.

The parameters to control the transaction are passed in by the user in the CTxDefinition parameter.

The returned value is a newly-instantiated CTxDefinition object, derived from the input parameter.

Parameters:
ctxDefinition - The input CTxDefinition. It must not be null. Only some fields are used; see below for usage and the transformation to the output value.
Returns:
The CTxDefinition. The returned value is the input parameter - the same instance - but with values filled in or changed. The transformations to create the returned CTxDefinition fields are:
name
the name field is unchanged: if it is null when start() is called, it will be null on output.

It is a good idea to set this to a non-null unique value, because you can then discover what happened to the transaction. It also provides you with protection against programming errors: CloudTran catches transactions that use the same business transaction ID that have not been aborted. (In other words, you can reissue a transaction that has been aborted for some reason; otherwise, a retry is a programming error.)

The method throws the TransactionExceptionNameUsedBefore if you issue a start with a duplicate businsess transaction that is still active or committed.

transactionTimeout
can be set to a non-null value, giving the timeout in milliseconds. Otherwise the default will apply.

You will most likely want to set this if you anticipate a very long transaction.

internalTxId
the input value of the internalTxId is ignored. start() allocates a new and unique internalTxId for each call to start.
Throws:
TransactionExceptionRetriable
TransactionExceptionNameUsedBefore

commit

void commit(CTxDefinition ctxDefinition)
            throws TransactionExceptionRetriable
Commits the transaction from the client. If the transaction has been previously aborted because it timed out at the TxB, the transaction cannot now be committed, so this method throws a TransactionExceptionRetriable.

Throws:
TransactionExceptionRetriable

abort

void abort(CTxDefinition ctxDefinition)
           throws TransactionExceptionRetriable
Aborts the transaction from the client. If the transaction has been previously aborted because it timed out at the TxB, this throws a TransactionExceptionRetriable.

Throws:
TransactionExceptionRetriable

getTransactionStatus

com.cloudtran.shared.TransactionInstruction getTransactionStatus(long internalTxId)
                                                                 throws TransactionExceptionRetriable
Throws:
TransactionExceptionRetriable

whatHappenedTo

byte whatHappenedTo(String name)
                    throws TransactionExceptionNonRetriable
Call this method to find out what happened to a transaction based on its business transaction named with the name parameter.

This method only does something in GigaSpaces; in Coherence, it returns null.

This method is useful when a call to commit the transaction has timed out. In that case, it is may be that the TxB primary has gone down ... in which case recovery may be still in process

However, it could also be that the transaction is too large to complete in the allocted time or there was a transient network. It may be worth calling this method: if the returned status is COMMITTING or COMMITTED, there is no need to retry the transaction

The name parameter must not be null: a TransactionExceptionNonRetriable is thrown in this case. If the transaction name is unknown, the returned value is null. The name may be unknown because the memory of the transaction has already been flushed from the system. Currently, the transaction buffer flushes its memory of these transactions after a configurable time. Therefore, if the original transaction failed at some time ago, this will return null.

Throws:
TransactionExceptionNonRetriable

whatHappenedTo

com.cloudtran.shared.CTxInfo whatHappenedTo(long internalTxId)
                                            throws TransactionExceptionNonRetriable
Call this method to find out what happened to a transaction based on its internal transaction id 'internalTxId'.

This method is useful when a call to commit the transaction has timed out.

In that case, it is may be that the TxB primary has gone down ... in which case recovery may be still in process

However, it could also be that the transaction is too large to complete in the allocted time or there was a transient network. It may be worth calling this method: if the returned status is COMMITTING or COMMITTED, there is no need to retry the transaction

The internalTxId parameter must not be null: a TransactionExceptionNonRetriable is thrown in this case.

Throws:
TransactionExceptionNonRetriable

waitForAllComplete

void waitForAllComplete()
wait for all transactions to be completed. This means they are all - logged if necessary, - committed to cohort spaces and - persisted to datasources.


getNanoTime

long getNanoTime()
getNanoTime() is used to synchronise our watches. This is used in our testing rig to coordinate nano time between boxes, so that an aggregated and sorted trace of execution should have cross-JVM calls in the right order.


getNanoTimeToMillisAdjustment

long getNanoTimeToMillisAdjustment()
getNanoTimeMillisAdjustment() is used to synchronise our watches. It is the nano time of the current system time This is used in our testing rig to coordinate nano time between boxes, so that an aggregated and sorted trace of execution should have cross-JVM calls in the right order. On Coherence, this calls to the initial primary Isolator node. On GigaSpaces, it calls to the initial primary Coordinator node.


txAbortedByCohort

void txAbortedByCohort(CTxDefinition ctxDefinition)
                       throws TransactionExceptionNonRetriable
This is internal to CloudTran implementation: clients of the CloudTran platform shouldn't use it. This indicates that something has happened to cause a transaction to be aborted at the cohort, and that a final 'commit()' from the client should be turned into a 'PreviouslyAborted' exception and the transaction aborted rather than committed.

Throws:
TransactionExceptionNonRetriable

abortIfActive

com.cloudtran.shared.TransactionInstruction abortIfActive(long internalTxId)
                                                          throws TransactionExceptionNonRetriable
This is internal to CloudTran implementation: clients of the CloudTran platform shouldn't use it. This is called by the cohort when it is waking up (in Cohort.onAfterPrimary()). The distributed transaction passed is in the ACTIVE state in the Cohort. However, CloudTran policy is not to allow distributed transactions to be ACTIVE across a participant cohort's failover. This is because the previous primary could have had read locks on objects in the space; these are lost during failover because GigaSpaces local transactions do not fail over. (The reason for this policy is that the cost of keeping the read locks is very high - the benefits are low (a small percentage of transactions failing) versus the extra cost of communicating all read locks to the TxB). The input parameter is the internalTxId identifying the transaction. The TxB returns the transaction status so the cohort can report it. If the returned status is ACTIVE, then the transaction will be marked 'abortedByCohort' so that it will be aborted if the client eventually calls commit() for the transaction. If the transaction is unknown, null is returned.

Throws:
TransactionExceptionNonRetriable

isOpenForBusiness

boolean isOpenForBusiness()
The "Open for Business" flag is used by both clients and CloudTran internally. The state, reflected in the 'openForBusiness' flag, is initially false. After all the application initialisation is done in a given PU instance (as primary), the openForBusiness state is set true, which writes a marker into the space and sets the 'openForBusiness' flag true.

Once the 'openForBusiness' flag is set, it is never unset.

The application initialisation code in PUs, which includes the CoordinatorPU, can use this marker to determine at start of day (i.e. when it becomes primary), whether this is the first initialisation ('isOpenForBusiness()' returns false) or a re-initialisation of a space (e.g. after a fail-over or on scaling up).

As an example, the CoordinatorPU uses this to either loadAllData (on first initialisation) or recover transactions (on subsequent initialisations).