com.cloudtran.api
Class DefaultCTxDefinition

java.lang.Object
  extended by com.cloudtran.api.DefaultCTxDefinition
All Implemented Interfaces:
CTxDefinition, Externalizable, Serializable, Cloneable

public class DefaultCTxDefinition
extends Object
implements Externalizable, Cloneable, CTxDefinition

Defines parameters for starting a transaction and is also the serializable transaction context object. It is passed into the TxB.start() call.

An adjusted version of the object (with defaults and internalTxId filled in) is returned from transaction manager after starting a transaction. The adjusted version is a different object instance, so the original input parameter object is left unchanged.

DefaultCTxDefinition is used as the 'transaction context', to instruct the transaction manager to commit/rollback and to communicate the transaction between nodes cooperating in a distributed transaction.

See Also:
Serialized Form

Field Summary
 int cohortTransactionHearbeatPeriod
          The time, in milliseconds, for the cohort to try to complete the transaction.
static short defaultTransactionType
          The default transaction type.
 long internalTxId
          The internal CloudTran transaction identifier.
 boolean logAfterCommit
          The caller can specify if he wants to log the transaction before or after committing it.
 boolean logBeforeCommit
          Set this true to have CloudTran log the transaction before committing it, which protects against complete cluster failure.
 short mvccUpdatePolicy
          This is the update policy for MVCC.
 String name
          This field defines a transaction name.
 int persistLingerTimeMillis
           
static int persistLingerTimeMillisDefault
           
 boolean prepareFromManager
          This turns on preparing at the manager.
 Long remoteTxId
          The remoteTxId is the internalTxId from the originating data center.
 long startTime
          The startTime is the CloudTran global time when the transaction started.
 int transactionTimeout
          The time, in milliseconds, after which the TxBufferManager should time out the transaction.
 short transactionType
          transactionType is the type of transaction to be requested at 'start'.
 boolean useClientCache
          This turns on client caching.
 
Fields inherited from interface com.cloudtran.api.CTxDefinition
DEFAULT_COHORT_TRANSACTION_HEARTBEAT_PERIOD, DEFAULT_TRANSACTION_TIMEOUT, TX_TYPE_COH_LLAPI_MVCC, TX_TYPE_COH_LLAPI_PL, TX_TYPE_COH_TLG, TX_TYPE_GS, UPDATECHECK_NONE, UPDATECHECK_READWRITE, UPDATECHECK_WRITE
 
Constructor Summary
DefaultCTxDefinition()
           
DefaultCTxDefinition(com.cloudtran.shared.CTxInfo ctxInfo)
          This method is called when we are in the recommit scenario in Coherence.
 
Method Summary
 Object clone()
           
 DefaultCTxDefinition getClone()
           
 int getCohortTransactionHearbeatPeriod()
           
 String getIds()
           
 long getInternalTxId()
           
 short getMvccUpdatePolicy()
           
 String getMvccUpdatePolicyName()
           
static String getMvccUpdatePolicyName(short mvccUpdatePolicy)
           
 String getName()
           
 int getPersistLingerTimeMillis()
           
static int getPersistlingertimemillisdefault()
           
static int getPersistLingerTimeMillisDefault()
           
 Long getRemoteTxId()
           
 long getStartTime()
           
 int getTransactionTimeout()
           
 short getTransactionType()
          returns the transaction type, based on the TX_TYPE_* constants (GigaSpaces, TopLink Grid, LLAPI-MVCC, LLAPI-PL).
 String getTransactionTypeName()
          returns the transaction type as a string, based on the TX_TYPE_* constants, such as "TX_TYPE_COH_LLAPI_MVCC".
static String getTransactionTypeName(short transactionType)
           
 short getUpdatePolicy()
           
 boolean getUseClientCache()
           
 boolean isLogAfterCommit()
           
 boolean isLogBeforeCommit()
           
 boolean isPrepareFromManager()
           
 boolean isTransactionTypeLLAPI()
           
static boolean isTransactionTypeLLAPI(short transactionType)
           
static void main(String[] args)
           
 void readExternal(ObjectInput in)
           
 void setCohortTransactionHearbeatPeriod(int cohortTransactionHearbeatPeriod)
           
 void setInternalTxId(long internalTxId)
           
 void setLogAfterCommit(boolean logAfterCommit)
           
 void setLogBeforeCommit(boolean logBeforeCommit)
           
 void setMvccUpdatePolicy(short mvccUpdatePolicy)
           
 void setName(String name)
           
 void setPersistLingerTimeMillis(int persistLingerTimeMillis)
           
 void setPrepareFromManager(boolean prepareFromManager)
           
 void setRemoteTxId(Long remoteTxId)
           
 void setStartTime(long startTime)
           
 void setTransactionTimeout(int transactionTimeout)
          This is the amount of milliseconds to delay before timing out the transaction.
 void setTransactionType(short t)
           
 void setUpdatePolicy(short mvccUpdatePolicy)
           
 void setUseClientCache(boolean useClientCache)
           
 String toString()
           
 boolean useClientCache()
           
 void writeExternal(ObjectOutput out)
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

name

public String name
This field defines a transaction name. The idea is that it should be useful to business users or operators. For example, it enables cross-system tracking.

When you initially pass the DefaultCTxDefinition object into the txBufferManager.start(), you can define this field yourself.

By default, this field is null; CloudTran does not set it.

In GigaSpaces, you can use this field to look up a transaction state using 'whatHappenedTo'. In Coherence, this is not available.


transactionTimeout

public int transactionTimeout
The time, in milliseconds, after which the TxBufferManager should time out the transaction. Once this timeout is reached the transaction will be aborted unilaterally by the TxBufferManager. Calls from the client or the cohorts to commit or abort the transaction will get a TransactionExceptionRetriable exception indicating the transactionTimeout has been triggered.

This can be quite long - for very large transactions it could be minutes. The upward pressure on this value is to avoid unnecessary timeouts. The downward pressure is that, when errors occur, objects updated in the cohort by the transaction will be locked until this times out.

The default is CTxDefinition.DEFAULT_TRANSACTION_TIMEOUT.


cohortTransactionHearbeatPeriod

public int cohortTransactionHearbeatPeriod
The time, in milliseconds, for the cohort to try to complete the transaction. This field is only used in GigaSpaces.

This number becomes relevant when either the TxB has gone down or become unreachable, for example if it is reconfiguring. The cohort then uses this timeout period to time calls to ask the TxB what to do with its subtransaction.

This can be quite long - the default is 15 seconds.

The upward pressure on this value is to avoid flooding the TxB with useless calls, and should therefore be at least as long as the network connection timeout value. The downward pressure on this value is to release resources in the cohort as quickly as possible because, until a sub-transaction is committed in the cohort, objects updated in the cohort by the transaction will be locked until the situation is resolved.


internalTxId

public long internalTxId
The internal CloudTran transaction identifier.

Normally, this is left null by the client when calling TxB.start(). In this case, it is allocated by the TxB during the start call, in such a way that the complete application can handle 1 million transactions per second without the transaction ID allocation scheme being a problem. In practice, this means at start of day, in production, the first transaction allocation ID is calculated as a long by multiplying the System.currentTimeMillis() by 1000 and then allocating from there.

If this is specified by the client,it must be guaranteed to be unique across all transactions in the complete application.

This value must NOT be changed changed by applications after the start call. (If it is changed, the result is undefined ... but an InternalException is quite likely.)


remoteTxId

public Long remoteTxId
The remoteTxId is the internalTxId from the originating data center. On the local data center, a replicated transaction will be created with its own internalTxId, different from the remoteTxId. This also serves as an indication as to whether to replicate this transaction: if remoteTxId is non-null, we mustn't replicate. This value is normally set by the CloudTran replication system. Normally, callers should only set this value as part of their own replication system.


logBeforeCommit

public boolean logBeforeCommit
Set this true to have CloudTran log the transaction before committing it, which protects against complete cluster failure.

While it is also possible to set logAfterCommit, this is used only in special circumstances.

It is an error if both logBeforeCommit and logAfterCommit are set true.

This is only used if there is data to be persisted; if there is no data to be persisted for a given transaction, then the transaction is not logged.


logAfterCommit

public boolean logAfterCommit
The caller can specify if he wants to log the transaction before or after committing it. It is an error if both logBeforeCommit and logAfterCommit are set true.

To protect against complete cluster failure, it may be sufficient to set logAfterCommit=true if SSD's are being used because they are fast enough that the transaction log will occur before the transaction commit() method returns.


startTime

public long startTime
The startTime is the CloudTran global time when the transaction started. It is required to do MVCC operations from the client into the grid.


defaultTransactionType

public static short defaultTransactionType
The default transaction type. This value is used to set the transactionType when a new DefaultCTxDefinition is created.

To start an MVCC transaction in Coherence, you can avoid setting the transaction type explicitly by calling CTx.startMvcc().


transactionType

public short transactionType
transactionType is the type of transaction to be requested at 'start'. The value should be one of the "TX_TYPE_..." constants in this class. The default will be changed by the initialization - to TX_TYPE_GS in GigaSpaces and to TX_TYPE_COH_LLAPI_PL in Coherence.

If you are using the LLAPI, you can start an MVCC transaction by calling CTx.startMvcc(), which simply sets this field equal to TX_TYPE_COH_LLAPI_MVCC and then starts the transaction.


mvccUpdatePolicy

public short mvccUpdatePolicy
This is the update policy for MVCC. Note that in addition to the policy options, it is possible to specify a filter on individual cache 'put' operations in the transaction.

The policy options specified here apply to all transactional cache 'put' operations after 'commit()' is called.


useClientCache

public boolean useClientCache
This turns on client caching. When false, no values are cached at the client by CloudTran: all reads and writes go to the Coherence cache. For more information, see the manual section on Client Caching.


prepareFromManager

public boolean prepareFromManager
This turns on preparing at the manager. It is only relevant when client caching is turned off (because cache updates are not made by the client).

When false, prepares are sent from the client. When true, cache updates from the client are not consistency checked; the cache node operates as a level 2 cache for the transaction, so multiple nodes can keep track of a cache value as it is changed during the transaction. no values are cached at the client by CloudTran: all reads and writes go to the Coherence cache.

For more information, see the manual section on Prepare From Manager.


persistLingerTimeMillisDefault

public static final int persistLingerTimeMillisDefault

persistLingerTimeMillis

public int persistLingerTimeMillis
Constructor Detail

DefaultCTxDefinition

public DefaultCTxDefinition()

DefaultCTxDefinition

public DefaultCTxDefinition(com.cloudtran.shared.CTxInfo ctxInfo)
This method is called when we are in the recommit scenario in Coherence. At that point, we pretend to do a commit as though from the user. The user commit() method needs the DefaultCTxDefinition and we have the ctxInfo in our hand. This constructor creates the DefaultCTxDefinition we need to simulate the user call.

Method Detail

getName

public String getName()
Specified by:
getName in interface CTxDefinition

setName

public void setName(String name)
Specified by:
setName in interface CTxDefinition

getTransactionTimeout

public int getTransactionTimeout()
Specified by:
getTransactionTimeout in interface CTxDefinition

setTransactionTimeout

public void setTransactionTimeout(int transactionTimeout)
Description copied from interface: CTxDefinition
This is the amount of milliseconds to delay before timing out the transaction.

Specified by:
setTransactionTimeout in interface CTxDefinition

getCohortTransactionHearbeatPeriod

public int getCohortTransactionHearbeatPeriod()
Specified by:
getCohortTransactionHearbeatPeriod in interface CTxDefinition

setCohortTransactionHearbeatPeriod

public void setCohortTransactionHearbeatPeriod(int cohortTransactionHearbeatPeriod)
Specified by:
setCohortTransactionHearbeatPeriod in interface CTxDefinition

getInternalTxId

public long getInternalTxId()
Specified by:
getInternalTxId in interface CTxDefinition

setInternalTxId

public void setInternalTxId(long internalTxId)
Specified by:
setInternalTxId in interface CTxDefinition

getPersistLingerTimeMillis

public int getPersistLingerTimeMillis()
Specified by:
getPersistLingerTimeMillis in interface CTxDefinition

setPersistLingerTimeMillis

public void setPersistLingerTimeMillis(int persistLingerTimeMillis)
Specified by:
setPersistLingerTimeMillis in interface CTxDefinition

getIds

public String getIds()
Specified by:
getIds in interface CTxDefinition
Returns:
gets the 'ids' for the transaction. This will be at least an unique transaction number (e.g. 12345678). If the name has been specified for the transaction, that will be shown too (e.g. "12345678/TxName");

isLogBeforeCommit

public boolean isLogBeforeCommit()
Specified by:
isLogBeforeCommit in interface CTxDefinition

isLogAfterCommit

public boolean isLogAfterCommit()
Specified by:
isLogAfterCommit in interface CTxDefinition

setLogBeforeCommit

public void setLogBeforeCommit(boolean logBeforeCommit)
Specified by:
setLogBeforeCommit in interface CTxDefinition

setLogAfterCommit

public void setLogAfterCommit(boolean logAfterCommit)
Specified by:
setLogAfterCommit in interface CTxDefinition

getTransactionType

public short getTransactionType()
Description copied from interface: CTxDefinition
returns the transaction type, based on the TX_TYPE_* constants (GigaSpaces, TopLink Grid, LLAPI-MVCC, LLAPI-PL).

Specified by:
getTransactionType in interface CTxDefinition

setTransactionType

public void setTransactionType(short t)
Specified by:
setTransactionType in interface CTxDefinition

isTransactionTypeLLAPI

public boolean isTransactionTypeLLAPI()
Specified by:
isTransactionTypeLLAPI in interface CTxDefinition

isTransactionTypeLLAPI

public static boolean isTransactionTypeLLAPI(short transactionType)

getTransactionTypeName

public String getTransactionTypeName()
Description copied from interface: CTxDefinition
returns the transaction type as a string, based on the TX_TYPE_* constants, such as "TX_TYPE_COH_LLAPI_MVCC".

Specified by:
getTransactionTypeName in interface CTxDefinition

getTransactionTypeName

public static String getTransactionTypeName(short transactionType)

getMvccUpdatePolicyName

public String getMvccUpdatePolicyName()
Specified by:
getMvccUpdatePolicyName in interface CTxDefinition

getMvccUpdatePolicyName

public static String getMvccUpdatePolicyName(short mvccUpdatePolicy)

toString

public String toString()
Overrides:
toString in class Object

clone

public Object clone()
Overrides:
clone in class Object

getClone

public DefaultCTxDefinition getClone()
Specified by:
getClone in interface CTxDefinition

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException
Specified by:
readExternal in interface Externalizable
Throws:
IOException
ClassNotFoundException

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException
Specified by:
writeExternal in interface Externalizable
Throws:
IOException

main

public static void main(String[] args)
                 throws FileNotFoundException,
                        IOException,
                        ClassNotFoundException
Throws:
FileNotFoundException
IOException
ClassNotFoundException

getRemoteTxId

public Long getRemoteTxId()
Specified by:
getRemoteTxId in interface CTxDefinition

setRemoteTxId

public void setRemoteTxId(Long remoteTxId)
Specified by:
setRemoteTxId in interface CTxDefinition

getPersistLingerTimeMillisDefault

public static int getPersistLingerTimeMillisDefault()

useClientCache

public boolean useClientCache()
Specified by:
useClientCache in interface CTxDefinition
Returns:
true is 'useClientCache' flag has been set

setUseClientCache

public void setUseClientCache(boolean useClientCache)
Specified by:
setUseClientCache in interface CTxDefinition

getStartTime

public long getStartTime()
Specified by:
getStartTime in interface CTxDefinition

setStartTime

public void setStartTime(long startTime)
Specified by:
setStartTime in interface CTxDefinition

getUpdatePolicy

public short getUpdatePolicy()
Specified by:
getUpdatePolicy in interface CTxDefinition

setUpdatePolicy

public void setUpdatePolicy(short mvccUpdatePolicy)
Specified by:
setUpdatePolicy in interface CTxDefinition

getMvccUpdatePolicy

public short getMvccUpdatePolicy()
Specified by:
getMvccUpdatePolicy in interface CTxDefinition

setMvccUpdatePolicy

public void setMvccUpdatePolicy(short mvccUpdatePolicy)
Specified by:
setMvccUpdatePolicy in interface CTxDefinition

getUseClientCache

public boolean getUseClientCache()
Specified by:
getUseClientCache in interface CTxDefinition

getPersistlingertimemillisdefault

public static int getPersistlingertimemillisdefault()

isPrepareFromManager

public boolean isPrepareFromManager()
Specified by:
isPrepareFromManager in interface CTxDefinition

setPrepareFromManager

public void setPrepareFromManager(boolean prepareFromManager)
Specified by:
setPrepareFromManager in interface CTxDefinition