Chapter 28. The javax.transaction Package

HeuristicCommitException	JTA 1.0
javax.transaction	serializable checked

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

HeuristicMixedException	JTA 1.0
javax.transaction	serializable checked

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()

HeuristicRollbackException	JTA 1.0
javax.transaction	serializable checked

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()

InvalidTransactionException	JTA 1.0
javax.transaction	serializable checked

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()

NotSupportedException	JTA 1.0
javax.transaction	serializable checked

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()

RollbackException	JTA 1.0
javax.transaction	serializable checked

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()

Status	JTA 1.0
javax.transaction

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.

Synchronization	JTA 1.0
javax.transaction

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()

SystemException	JTA 1.0
javax.transaction	serializable checked

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()}

Transaction	JTA 1.0
javax.transaction

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()}

TransactionManager	JTA 1.0
javax.transaction

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.

TransactionRequiredException	JTA 1.0
javax.transaction	serializable checked

Thrown when a transaction-related operation is requested, but there is no active transaction.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->java.rmi.RemoteException-->TransactionRequiredException

TransactionRolledbackException	JTA 1.0
javax.transaction	serializable checked

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	JTA 1.0
javax.transaction

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.