At times, you may need to demarcate transactions in your code. Generally, you should use programmatic demarcation as little as possible, as it is error-prone and can interfere with the application server’s own transaction demarcation mechanisms. If you find it necessary to use programmatic demarcation, you must be very careful to ensure that your code handles any unexpected errors and conditions.
The ATG platform includes two classes that you can use to demarcate transactions in code:
atg.dtm.UserTransactionDemarcation
can be used by J2EE components and Nucleus components to perform basic transaction demarcation. This class accesses theUserTransaction
object to perform its operations.atg.dtm.TransactionDemarcation
can be used by Nucleus components to demarcate areas of code at a fine granularity. J2EE components cannot use this class, because it accesses theTransactionManager
object directly.
Using the UserTransactionDemarcation Class
The following example illustrates how to use the UserTransactionDemarcation
class:
UserTransactionDemarcation td = new UserTransactionDemarcation (); try { try { td.begin (); ... do transactional work ... } finally { td.end (); } } catch (TransactionDemarcationException exc) { ... handle the exception ... }
There are a few things to note about using the UserTransactionDemarcation
class:
The
begin()
method implements theREQUIRED
transaction mode only. If there is no transaction in place, it creates a new one; but if a transaction is already in place, that transaction is used.If the
begin()
method creates a new transaction, theend()
method commits that transaction, unless it is marked for rollback only, in which case theend()
method rolls it back. However, if thebegin()
method does not create a transaction (because there is already a transaction in place), theend()
method does nothing.The code must ensure that the
end()
method is always called, typically by using afinally
block.The
begin()
andend()
methods can throw exceptions of classatg.dtm.TransactionDemarcationException
. The calling code should log or handle these exceptions.
Using the TransactionDemarcation Class
The following example illustrates using the TransactionDemarcation
class:
TransactionManager tm = ... TransactionDemarcation td = new TransactionDemarcation (); try { try { td.begin (tm, td.REQUIRED); ... do transactional work ... } finally { td.end (); } } catch (TransactionDemarcationException exc) { ... handle the exception ... }
There are a few things to note about using the TransactionDemarcation
class:
The
begin()
method takes two arguments. The first argument is theTransactionManager
object. The second argument specifies one of the 6 transaction modes:REQUIRED
,REQUIRES_NEW
,SUPPORTS
,NOT_SUPPORTED
,MANDATORY
, orNEVER
. If the second argument is not supplied, it defaults toREQUIRED
.The code must ensure that the
end()
method is always called, typically by using afinally
block.The
begin()
andend()
methods can throw exceptions of classatg.dtm.TransactionDemarcationException
. The calling code should log or handle these exceptions.
The TransactionDemarcation
class takes care of both creating and ending transactions. For example, if the TransactionDemarcation
object is used with a RequiresNew
transaction mode, then the end()
call will take care of committing or rolling back the transaction created by the begin()
call. The application is not expected to commit or rollback the transaction itself.
If for some reason the application needs to force the transaction to end, this can be done by calling the TransactionManager.commit()
method:
TransactionManager tm = ... TransactionDemarcation td = new TransactionDemarcation (); try { try { td.begin (tm); ... do transactional work ... tm.commit (); } catch (RollbackException exc) { ... } catch (HeuristicMixedException exc) { ... } catch (HeuristicRollbackException exc) { ... } catch (SystemException exc) { ... } catch (SecurityException exc) { ... } catch (IllegalStateException exc) { ... } finally { td.end (); } } catch (TransactionDemarcationException exc) { ... handle the exception ... }
Ending a transaction in this way should be avoided wherever possible, because handling all of the exceptions introduces a lot of complexity in the code. The same result can usually be accomplished by more standard means.