com.arjuna.mw.wst
Class UserTransaction

java.lang.Object
  com.arjuna.mw.wst.UserTransaction

public abstract class UserTransaction

extends java.lang.Object

This is the interface that allows transactions to be started and terminated. The messaging layer converts the Commit, Rollback and Notify messages into calls on this. Importantly, a UserTransaction does not represent a specific transaction, but rather is responsible for providing access to an implicit per-thread transaction context; it is similar to the UserTransaction in the JTA specification. Therefore, all of the UserTransaction methods implicitly act on the current thread of control.

Since:

XTS 1.0.

Version:

$Id: UserTransaction.java,v 1.8.4.1 2005/11/22 10:36:05 kconner Exp $

Author:

Mark Little (mark.little@arjuna.com)

Constructor Summary

UserTransaction()

Method Summary

abstract void	begin() Start a new transaction.
abstract void	begin(int timeout) Start a new transaction with the specified timeout as its lifetime.
abstract void	commit() The transaction is committed by the commit method.
static UserTransaction	getUserTransaction() Get the user transaction.
abstract void	rollback() The rollback operation will terminate the transaction and return normally if it succeeded, while throwing an appropriate exception if it didn't.
static void	setUserTransaction(UserTransaction userTransaction) Set the user transaction.
abstract java.lang.String	transactionIdentifier()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UserTransaction

public UserTransaction()

Method Detail

getUserTransaction

public static UserTransaction getUserTransaction()

Get the user transaction.

Returns:

the user transaction.

setUserTransaction

public static void setUserTransaction(UserTransaction userTransaction)

Set the user transaction.

Parameters:

userTransaction - The user transaction.

begin

public abstract void begin()
                    throws WrongStateException,
                           SystemException

Start a new transaction. If one is already associated with this thread then the WrongStateException will be thrown. Upon success, this operation associates the newly created transaction with the current thread.

Throws:

WrongStateException

SystemException

begin

public abstract void begin(int timeout)
                    throws WrongStateException,
                           SystemException

Start a new transaction with the specified timeout as its lifetime. If one is already associated with this thread then the WrongStateException will be thrown.

Throws:

WrongStateException

SystemException

commit

public abstract void commit()
                     throws TransactionRolledBackException,
                            UnknownTransactionException,
                            java.lang.SecurityException,
                            SystemException

The transaction is committed by the commit method. This will execute the PhaseZero, 2PC and OutcomeNotification protocols prior to returning. If there is no transaction associated with the invoking thread then UnknownTransactionException is thrown. If the transaction ultimately rolls back then the TransactionRolledBackException is thrown. When complete, this operation disassociates the transaction from the current thread such that it becomes associated with no transaction.

Throws:

TransactionRolledBackException

UnknownTransactionException

java.lang.SecurityException

SystemException

rollback

public abstract void rollback()
                       throws UnknownTransactionException,
                              java.lang.SecurityException,
                              SystemException

The rollback operation will terminate the transaction and return normally if it succeeded, while throwing an appropriate exception if it didn't. If there is no transaction associated with the invoking thread then UnknownTransactionException is thrown.

Throws:

UnknownTransactionException

java.lang.SecurityException

SystemException

transactionIdentifier

public abstract java.lang.String transactionIdentifier()