Chapter 28. The javax.transaction PackageThe javax.transaction package is the main package in the Java Transaction API (JTA). The JTA defines the interfaces needed to interact with a transaction manager. A transaction manager sits in between an application and some shared resource, such as a relational database or a messaging service, and ensures that transactional interactions between the two are handled correctly. An application server interacts directly with the transaction manager on behalf of client applications. An application server uses the TransactionManager interface and Transaction objects, while a client application acquires UserTransaction objects through the application server. Figure 28-1 shows the class hierarchy for the javax.transaction package. Figure 28-1. The javax.transaction package
Thrown when an attempt is made to roll back a resource whose updates have been committed due to a heuristic decision (e.g., a resource lost contact with the transaction manager and decided to commit after one phase of a two-phase commit).
Hierarchy: Object-->Throwable(Serializable)-->Exception-->HeuristicCommitException
Thrown by the commit() methods on Transaction and UserTransaction to indicate that some updates were rolled back due to a heuristic decision (e.g., some resources involved in a transaction lost contact with the transaction manager and decided to rollback, but some others had already committed).
Hierarchy: Object-->Throwable(Serializable)-->Exception-->HeuristicMixedException Thrown By: Transaction.commit(), TransactionManager.commit(), UserTransaction.commit()
Thrown by the commit() methods on Transaction and UserTransaction to indicate that the transaction has been rolled back due to a heuristic decision (e.g., the resource lost contact with the transaction manager and decided to abort the transaction).
Hierarchy: Object-->Throwable(Serializable)-->Exception-->HeuristicRollbackException Thrown By: Transaction.commit(), TransactionManager.commit(), UserTransaction.commit()
Thrown when an attempt is made to operate on a transaction that is in an invalid state.
Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->java.rmi.RemoteException-->InvalidTransactionException Thrown By: TransactionManager.resume()
Thrown when a request is made for an unsupported operation. Typically thrown by the transaction manager when an attempt is made to create a nested exception and these are not supported by the transaction manager.
Hierarchy: Object-->Throwable(Serializable)-->Exception-->NotSupportedException Thrown By: TransactionManager.begin(), UserTransaction.begin()
Thrown when an invalid operation is requested on a transaction that has either rolled back or been marked for rollback-only (e.g., calling TransactionManager.enlistResource() on such a transaction).
Hierarchy: Object-->Throwable(Serializable)-->Exception-->RollbackException Thrown By: Transaction.{commit(), enlistResource(), registerSynchronization()}, TransactionManager.commit(), UserTransaction.commit()
This interface simply serves to hold static integer status codes for transactions. The Transaction.getStatus() method can query the status of a transaction, and these codes indicate the meaning of the returned value.
A Synchronization object gets notification of the end of a transaction. The Synchronization interface must be implemented by a concrete application class, which can then request callbacks from the transaction manager. The Synchronization object is registered with an active transaction by calling the Transaction.registerSynchronization() method, passing in the Synchronization object. An exception is thrown if the transaction is not active or has already been marked for rollback. Before the transaction manager starts the commit on the transaction, it calls the beforeCompletion() method on any registered Synchronization objects. After the transaction completes, the transaction manager calls the afterCompletion() method.
Passed To: Transaction.registerSynchronization()
Thrown by the transaction manager when a significant error occurs that effectively disables the manager.
Hierarchy: Object-->Throwable(Serializable)-->Exception-->SystemException Thrown By: Transaction.{commit(), delistResource(), enlistResource(), getStatus(), registerSynchronization(), rollback(), setRollbackOnly()}, TransactionManager.{begin(), commit(), getStatus(), getTransaction(), resume(), rollback(), setRollbackOnly(), setTransactionTimeout(), suspend()}, UserTransaction.{begin(), commit(), getStatus(), rollback(), setRollbackOnly(), setTransactionTimeout()}
A Transaction represents a global transaction managed by the transaction manager. When the TransactionManager interface is used directly (e.g., by an application server) to create and control transactions, Transaction objects represent the transactions created. The TransactionManager.getTransaction() method gets the transaction associated with the current thread. With the Transaction object, the caller can commit() or rollback() the Transaction, enlist or remove resources from the transaction, and get the status of the Transaction. The setRollbackOnly() method flags the Transaction so that it can be only rolled back, not committed. The registerSynchronization() method registers a Synchronization callback object with the Transaction.
Passed To: TransactionManager.resume() Returned By: TransactionManager.{getTransaction(), suspend()}
The TransactionManager interface is used by a transactional application server, such as an EJB server, to create and manage transactions on behalf of client applications. The application server can use the TransactionManager interface to create new transactions for the current thread, suspend and resume the current transaction, and commit or rollback the transaction. The setTransactionTimeout() method sets the timeout (in seconds) for any subsequent transactions started through the TransactionManager.
Thrown when a transaction-related operation is requested, but there is no active transaction.
Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->java.rmi.RemoteException-->TransactionRequiredException
Thrown when an operation requested on a particular transaction is irrelevant because the transaction has been rolled back.
Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->java.rmi.RemoteException-->TransactionRolledbackException
UserTransaction is the interface used by client applications to manage transactions. Typically, a transactional application server publishes a UserTransaction through JNDI, so a client gets a reference to the UserTransaction using a lookup on the JNDI Context. The client can use the UserTransaction to begin() a new transaction in the current thread. If there is already an active transaction in the current thread and the transaction manager does not support nested transactions, a NotSupportedException is thrown. The client can either commit() or rollback() the current transaction when it is complete. The setRollbackOnly() method flags the current transaction so that it can be only rolled back. The setTransactionTimeout() method sets the timeout, in seconds, of any subsequent transactions started through the transaction manager.
Copyright © 2001 O'Reilly & Associates. All rights reserved. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|