home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Book Home Java Enterprise in a Nutshell Search this book

Chapter 28. The javax.transaction Package

The 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

Figure 28-1. The javax.transaction package

HeuristicCommitExceptionJTA 1.0
javax.transactionserializable 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).

public class HeuristicCommitException extends Exception {
// Public Constructors
public HeuristicCommitException ();
public HeuristicCommitException (String msg);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->HeuristicCommitException

HeuristicMixedExceptionJTA 1.0
javax.transactionserializable 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).

public class HeuristicMixedException extends Exception {
// Public Constructors
public HeuristicMixedException ();
public HeuristicMixedException (String msg);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->HeuristicMixedException

Thrown By: Transaction.commit(), TransactionManager.commit(), UserTransaction.commit()

HeuristicRollbackExceptionJTA 1.0
javax.transactionserializable 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).

public class HeuristicRollbackException extends Exception {
// Public Constructors
public HeuristicRollbackException ();
public HeuristicRollbackException (String msg);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->HeuristicRollbackException

Thrown By: Transaction.commit(), TransactionManager.commit(), UserTransaction.commit()

InvalidTransactionExceptionJTA 1.0
javax.transactionserializable checked

Thrown when an attempt is made to operate on a transaction that is in an invalid state.

public class InvalidTransactionException extends java.rmi.RemoteException {
// Public Constructors
public InvalidTransactionException ();
public InvalidTransactionException (String msg);
}

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

Thrown By: TransactionManager.resume()

NotSupportedExceptionJTA 1.0
javax.transactionserializable 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.

public class NotSupportedException extends Exception {
// Public Constructors
public NotSupportedException ();
public NotSupportedException (String msg);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NotSupportedException

Thrown By: TransactionManager.begin(), UserTransaction.begin()

RollbackExceptionJTA 1.0
javax.transactionserializable 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).

public class RollbackException extends Exception {
// Public Constructors
public RollbackException ();
public RollbackException (String msg);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->RollbackException

Thrown By: Transaction.{commit(), enlistResource(), registerSynchronization()}, TransactionManager.commit(), UserTransaction.commit()

StatusJTA 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.

public abstract interface Status {
// Public Constants
public static final int STATUS_ACTIVE ; =0
public static final int STATUS_COMMITTED ; =3
public static final int STATUS_COMMITTING ; =8
public static final int STATUS_MARKED_ROLLBACK ; =1
public static final int STATUS_NO_TRANSACTION ; =6
public static final int STATUS_PREPARED ; =2
public static final int STATUS_PREPARING ; =7
public static final int STATUS_ROLLEDBACK ; =4
public static final int STATUS_ROLLING_BACK ; =9
public static final int STATUS_UNKNOWN ; =5
}
SynchronizationJTA 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.

public abstract interface Synchronization {
// Public Instance Methods
public abstract void afterCompletion (int status);
public abstract void beforeCompletion ();
}

Passed To: Transaction.registerSynchronization()

SystemExceptionJTA 1.0
javax.transactionserializable checked

Thrown by the transaction manager when a significant error occurs that effectively disables the manager.

public class SystemException extends Exception {
// Public Constructors
public SystemException ();
public SystemException (String s);
public SystemException (int errcode);
// Public Instance Fields
public int errorCode ;
}

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

TransactionJTA 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.

public abstract interface Transaction {
// Public Instance Methods
public abstract void commit () throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException, javax.transaction.SystemException;
public abstract boolean delistResource (javax.transaction.xa.XAResource xaRes, int flag) throws java.lang.IllegalStateException, javax.transaction.SystemException;
public abstract boolean enlistResource (javax.transaction.xa.XAResource xaRes) throws RollbackException, java.lang.IllegalStateException, javax.transaction.SystemException;
public abstract int getStatus () throws javax.transaction.SystemException;
public abstract void registerSynchronization (Synchronization sync) throws RollbackException, java.lang.IllegalStateException, javax.transaction.SystemException;
public abstract void rollback () throws java.lang.IllegalStateException, javax.transaction.SystemException;
public abstract void setRollbackOnly () throws java.lang.IllegalStateException, javax.transaction.SystemException;
}

Passed To: TransactionManager.resume()

Returned By: TransactionManager.{getTransaction(), suspend()}

TransactionManagerJTA 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.

public abstract interface TransactionManager {
// Public Instance Methods
public abstract void begin () throws NotSupportedException, javax.transaction.SystemException;
public abstract void commit () throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException, java.lang.IllegalStateException, javax.transaction.SystemException;
public abstract int getStatus () throws javax.transaction.SystemException;
public abstract Transaction getTransaction () throws javax.transaction.SystemException;
public abstract void resume (Transaction tobj) throws InvalidTransactionException, java.lang.IllegalStateException, javax.transaction.SystemException;
public abstract void rollback () throws java.lang.IllegalStateException, SecurityException, javax.transaction.SystemException;
public abstract void setRollbackOnly () throws java.lang.IllegalStateException, javax.transaction.SystemException;
public abstract void setTransactionTimeout (int seconds) throws javax.transaction.SystemException;
public abstract Transaction suspend () throws javax.transaction.SystemException;
}
TransactionRequiredExceptionJTA 1.0
javax.transactionserializable checked

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

public class TransactionRequiredException extends java.rmi.RemoteException {
// Public Constructors
public TransactionRequiredException ();
public TransactionRequiredException (String msg);
}

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

TransactionRolledbackExceptionJTA 1.0
javax.transactionserializable checked

Thrown when an operation requested on a particular transaction is irrelevant because the transaction has been rolled back.

public class TransactionRolledbackException extends java.rmi.RemoteException {
// Public Constructors
public TransactionRolledbackException ();
public TransactionRolledbackException (String msg);
}

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

UserTransactionJTA 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.

public abstract interface UserTransaction {
// Public Instance Methods
public abstract void begin () throws NotSupportedException, javax.transaction.SystemException;
public abstract void commit () throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException, java.lang.IllegalStateException, javax.transaction.SystemException;
public abstract int getStatus () throws javax.transaction.SystemException;
public abstract void rollback () throws java.lang.IllegalStateException, SecurityException, javax.transaction.SystemException;
public abstract void setRollbackOnly () throws java.lang.IllegalStateException, javax.transaction.SystemException;
public abstract void setTransactionTimeout (int seconds) throws javax.transaction.SystemException;
}


Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.