| This interface is somewhat reluctant addition by MetaBoss to the JTA specification.
It provides access to the rich transaction status information.
Problem description Java Transaction Architecture (JTA) Specification
defines very simple (almost too simple) transaction status mechanism.
Under this mechanism :
- Any transaction participant (eg. server doing some work in transaction) is able to mark
transaction for rollback via UserTransaction.setRollbackOnly() or Transaction.setRollbackOnly() methods.
- Any transaction participant can check the status of the current transaction via
UserTransaction.getStatus() and Transaction.getStatus() methods.
The facility to communicate more details about cause of rollback is absent. Such details may contain
an identity of the party, which have had a problem and the description of the problem
(may be in form of exception). Absence of this facility forces application programmers to invent
some "on-the-side" mechanisms to carry rich transaction status information in transaction context.
The addition of the cause exception to the java.lang.Throwable in Java 1.4.x offers some opportunity to
use cause in the HeuristicRollbackException to communicate the cause of rollback, but it is only helping the
code which has issued commit() instruction.
Solution description In order not to pollute JTA interfaces, separate ExtendedTransactionStatus
interface is introduced. The instance of this interface is obtainable via JNDI alongside with
javax.transaction.Transaction and javax.transaction.UserTransaction. This interface provides
facility to store and retrieve rollback cause together with transaction status. Because this interface is
an addition to JTA - it's usage (or decision not to use) remains entirely an application discretion.
We envisage that if and when JTA specification is enhanced (say UserTransaction and Transaction objects
will have similar facility in their interfaces) we will offer clients a smooth transition along the following lines:
- At this stage com.metaboss.enterprise.transaction.ExtendedTransactionStatus will be the only
component able to deliver this functionality. The implementation will reside in MetaBoss run-time libraries.
ExtendedTransactionStatus does not override JTA status management facilities, JTA components will have to be
used for setting transactions to rollback status and checking basic transaction status. This means that
client application code will be 100% compliant with J2EE and any other Java standard in this area.
- After JTA Interfaces are enhanced and able to offer similar facilities, the
com.metaboss.enterprise.transaction.ExtendedTransactionStatus interface will continue to offer this facility
but it will be deprecated and internal implementation will revert to JTA. If and when this occurs,
changes and schedule for deprecation and ultimate retirement of this interface will be communicated to clients.
- After a while (say one or two major release cycles or 12 month) com.metaboss.enterprise.transaction.ExtendedTransactionStatus
will be retired. There may also be some interim release where com.metaboss.enterprise.transaction.ExtendedTransactionStatus is present, but
each and every method throws javax.transaction.NotSupportedException
Usage description
To set transaction to rollback only after failure has occurred :
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.transaction.Transaction;
import com.metaboss.enterprise.transaction.ExtendedTransactionStatus;
...............................
...............................
try
{
...............................
...............................
}
catch(SomeBadException lShowStopperException)
{
Context lContext = new javax.naming.InitialContext();
Transaction lTransaction = (Transaction)lContext.lookup(com.metaboss.enterprise.transaction.Transaction.COMPONENT_URL);
ExtendedTransactionStatus lExtendedTransactionStatus = (ExtendedTransactionStatus)lContext.lookup(com.metaboss.enterprise.transaction.ExtendedTransactionStatus.COMPONENT_URL);
lTransaction.setRollbackOnly();
lExtendedTransactionStatus.setRollbackCause(lShowStopperException);
}
To check extended status after failure has occurred :
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.transaction.UserTransaction;
import javax.transaction.HeuristicRollbackException;
import com.metaboss.enterprise.transaction.ExtendedTransactionStatus;
...............................
...............................
Context lContext = new javax.naming.InitialContext();
try
{
UserTransaction lUserTransaction = (UserTransaction)lContext.lookup(com.metaboss.enterprise.transaction.UserTransaction.COMPONENT_URL);
...............................
...............................
...............................
lUserTransaction.commit();
}
catch(HeuristicRollbackException lRollbackException)
{
try
{
ExtendedTransactionStatus lExtendedTransactionStatus = (ExtendedTransactionStatus)lContext.lookup(com.metaboss.enterprise.transaction.ExtendedTransactionStatus.COMPONENT_URL);
Throwable lRollbackCauseException = lExtendedTransactionStatus.getRollbackCause();
if (lRollbackCauseException != null)
{
// Obtained ExtendedTransactionStatus object, and it has information about cause.
// Cause is known. Analyse it or report it
...............................
...............................
}
else
{
// Obtained ExtendedTransactionStatus object, but it does not have information about cause.
// Cause is unknown. Report this situation somehow
...............................
...............................
}
}
catch(javax.naming.NamingException lNamingException)
{
// Unable to obtain ExtendedTransactionStatus object.
// Cause is unknown. Report this situation somehow
...............................
...............................
}
}
|