atg.dtm
Class TransactionDemarcation

java.lang.Object
  atg.dtm.TransactionDemarcation

public class TransactionDemarcation
extends java.lang.Object

This is used by applications to demarcate transactions "by hand" around a section of code. An application will get or create one of these instances, then call begin() before the section of code. When the code finishes (preferably in a finally clause), end() should be called. Instances of this class are reusable, as long as begin/end is always called in sequence.

The begin method allows any of the transaction demarcation attributes specifed by EJB. If none is specified, it defaults to REQUIRED. Most of the time the transaction attribute will be REQUIRED or REQUIRES_NEW. The following explains all of the different transaction attribute types:

• NOT_SUPPORTED - if a transaction is in place, it is suspended in begin() and resumed in end(). The code in between executes in no transaction context.
• SUPPORTS - basically a pass-through - if a transaction is in place then it is used, otherwise no transaction is used.
• REQUIRED - if a transaction is not in place, then begin() will create a new transaction and end() will end it. If a transaction is in place, then that transaction is used. This is the most common usage, which basically insures that a transaction is around when it's needed.
• REQUIRES_NEW - begin() will suspend any current transaction then create a new one, and end() will end that transaction and resume the transaction (if any) that was suspended. This is the next most commmon usage - it insures that the code executes within its own transactoin.
• MANDATORY - this is a pass-through like SUPPORTS, except that this will throw an exception if no transaction is in place. It's more like an assertion than a behavior.
• NEVER - this is a pass-through like SUPPORTS, except that this will throw an exception if a transaction is in place. It's more like an assertion than a behavior.

The following is a sample use:

 TransactionDemarcation td = new TransactionDemarcation ();
 boolean success = false;
 try {
   td.begin (mTransactionManager);

   ... code to execute within the transaction ...

   success = true;
 }
 finally {
   td.end (!success);
 }
 

Field Summary

static java.lang.String	CLASS_VERSION Class version string
static int	MANDATORY
static int	NEVER
static int	NOT_SUPPORTED
static int	REQUIRED
static int	REQUIRES_NEW
static int	STATUS_CREATED_TRANSACTION_COMMITTED
static int	STATUS_SUSPENDED_TRANSACTION_RESUMED
static int	STATUS_TRANSACTION_CREATED
static int	STATUS_TRANSACTION_ENDED_IN_CODE
static int	SUPPORTS

Constructor Summary

TransactionDemarcation()
Constructs a new TransactionDemarcation

Method Summary

void	begin(javax.transaction.TransactionManager pTransactionManager) This should be called at the beginning of a section of code to be demarcated by a transaction.
void	begin(javax.transaction.TransactionManager pTransactionManager, int pTransAttribute) This should be called at the beginning of a section of code to be demarcated by a transaction.
int	end() This calls end with a rollback flag of false, meaning that it will commit the transaction unless it has been marked for rollback only.
int	end(boolean pRollback) This must be called at the end of a section of code demarcated by this TransactionDemarcation, preferably in a finally clause.
static boolean	equalTransactions(javax.transaction.Transaction pTransaction1, javax.transaction.Transaction pTransaction2) Compare two Transactions for equality.
javax.transaction.Transaction	getTransaction() Get the Transaction that is associated with this TransactionDemarcation;
boolean	isTransactionCreated() Return whether we created a transaction.
void	setClearTransactionOnEnd(boolean pClearTransactionOnEnd) Tells this TransactionDemarcation object to not clear the associated transaction when end() is called.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string

NOT_SUPPORTED

public static final int NOT_SUPPORTED

See Also:

Constant Field Values

SUPPORTS

public static final int SUPPORTS

See Also:

Constant Field Values

REQUIRED

public static final int REQUIRED

See Also:

Constant Field Values

REQUIRES_NEW

public static final int REQUIRES_NEW

See Also:

Constant Field Values

MANDATORY

public static final int MANDATORY

See Also:

Constant Field Values

NEVER

public static final int NEVER

See Also:

Constant Field Values

STATUS_TRANSACTION_CREATED

public static final int STATUS_TRANSACTION_CREATED

See Also:

Constant Field Values

STATUS_CREATED_TRANSACTION_COMMITTED

public static final int STATUS_CREATED_TRANSACTION_COMMITTED

See Also:

Constant Field Values

STATUS_SUSPENDED_TRANSACTION_RESUMED

public static final int STATUS_SUSPENDED_TRANSACTION_RESUMED

See Also:

Constant Field Values

STATUS_TRANSACTION_ENDED_IN_CODE

public static final int STATUS_TRANSACTION_ENDED_IN_CODE

See Also:

Constant Field Values

Constructor Detail

TransactionDemarcation

public TransactionDemarcation()

Constructs a new TransactionDemarcation

Method Detail

getTransaction

public javax.transaction.Transaction getTransaction()

Get the Transaction that is associated with this TransactionDemarcation;

setClearTransactionOnEnd

public void setClearTransactionOnEnd(boolean pClearTransactionOnEnd)

Tells this TransactionDemarcation object to not clear the associated transaction when end() is called. Setting this will make this object non-reusable.

begin

public void begin(javax.transaction.TransactionManager pTransactionManager,
                  int pTransAttribute)
           throws TransactionDemarcationException

This should be called at the beginning of a section of code to be demarcated by a transaction. The pTransAttribute specifies what kind of transactional behavior will be performed in the code, and should have the value NOT_SUPPORTED, SUPPORTS, REQUIRED, REQUIRES_NEW, MANDATORY, or NEVER. If this method returns successfully, then end() must be called on it at some point in the future.

Throws:

TransactionDemarcationException

begin

public void begin(javax.transaction.TransactionManager pTransactionManager)
           throws TransactionDemarcationException

This should be called at the beginning of a section of code to be demarcated by a transaction. This uses a default transaction attribute of REQUIRED, which is the most often used option. If this method returns successfully, then end() must be called on it at some point in the future.

Throws:

TransactionDemarcationException

end

public int end(boolean pRollback)
        throws TransactionDemarcationException

This must be called at the end of a section of code demarcated by this TransactionDemarcation, preferably in a finally clause. This will commit (or rollback if marked for rollback only) any created transaction, and resume any suspended transaction. If the demarcated code already committed the current transaction, everything is fine. But if the demarcated code changed the current transaction (by suspending and not resuming, or creating and not committing), an error is produced.

The pRollback flag indicates if the transaction should be rolled back. If true, the transaction will bve rolled back. If false, then the transaction will be rolled back only if it has been marked for rollback only.

This method returns a status code indicating what happened to the transactions during the demarcated area. The status code is a bitwise-OR of several flags, indicating the following:

• STATUS_TRANSACTION_CREATED - indicates that a transaction was started by the transaction demarcation, probably because it was executed with REQUIRED or REQUIRES_NEW
• STATUS_CREATED_TRANSACTION_COMMITTED - valid only if STATUS_TRANSACTION_CREATED is set - if set this indicates that the created transaction was successfully committed. If not set, then the created transaction was rolled back.
• STATUS_SUSPENDED_TRANSACTION_RESUMED - indicates that a transaction was suspended at the beginning of the transaction demarcation, then resumed afterwards, probably because it was executed with REQUIRES_NEW or NOT_SUPPORTED.
• STATUS_TRANSACTION_ENDED_IN_CODE - indicates that the code enclosed by the transaction demarcation ended the transaction itself - no further information is available about that transaction.

A typical use of the status flags is to see if a transaction was rolled back ((status & STATUS_TRANSACTION_CREATED != 0) && (status & STATUS_TRANSACTION_COMMITTED == 0)). But be aware - the only time this will be valid is if the code enclosed by the demarcation explicitly set the transaction to rollback only. If the transaction tried to commit and rolled back because of some other error, the result will be a rollback exception (enclosed in a TransactionDemarcationException).

Throws:

TransactionDemarcationException

end

public int end()
        throws TransactionDemarcationException

This calls end with a rollback flag of false, meaning that it will commit the transaction unless it has been marked for rollback only.

Throws:

TransactionDemarcationException

equalTransactions

public static final boolean equalTransactions(javax.transaction.Transaction pTransaction1,
                                              javax.transaction.Transaction pTransaction2)

Compare two Transactions for equality.

Parameters:

pTransaction1 - first transaction to compare

pTransaction2 - second transaction to compare

Returns:

true if both transactions are null or if the two transactions are equal according to equals(), else false.

isTransactionCreated

public boolean isTransactionCreated()

Return whether we created a transaction. If a transaction was already in place, this method returns null.