javax.transaction.xa

Interface XAResource

public interface XAResource

The XAResource interface is a Java mapping of the industry standard XA interface based on the X/Open CAE Specification (Distributed Transaction Processing: The XA Specification).

The XA interface defines the contract between a Resource Manager and a Transaction Manager in a distributed transaction processing (DTP) environment. An XA resource such as a JDBC driver or a JMS provider implements this interface to support association between a global transaction and a database or message service connection.

The XAResource interface can be supported by any transactional resource that is intended to be used by application programs in an environment where transactions are controlled by an external transaction manager. An example of such a resource is a database management system. An application may access data through multiple database connections. Each database connection is enlisted with the transaction manager as a transactional resource. The transaction manager obtains an XAResource for each connection participating in a global transaction. The transaction manager uses the start method to associate the global transaction with the resource, and it uses the end method to disassociate the transaction from the resource. The resource manager is responsible for associating the global transaction to all work performed on its data between the start and end method invocation.

At transaction commit time, the resource managers are informed by the transaction manager to prepare, commit, or rollback a transaction according to the two-phase commit protocol.

Behind the resources that implement this interface the resource manager exists. The resource manager does not have a public interface or direct references, and can manage several resources. To see if two resources are managed by the same resource manager, the isSameRM(XAResource) method can be used.

Version:

$Revision$

Field Summary

Fields

Modifier and Type	Field and Description
static int	TMENDRSCAN Flag value for the recover method indicating that the resource manager should end the current recovery scan.
static int	TMFAIL Flag value for the end method indicating that the transaction should be disassociated, and that the work has failed
static int	TMJOIN Flag value for the start method indicating that the resource should associate with a transaction previously seen by this resource manager.
static int	TMNOFLAGS Flag value indicating that no flags are set.
static int	TMONEPHASE JTA specifies this constant and states that it indicates that the caller is using one-phase optimization, but this constant seems not to be used by JTA.
static int	TMRESUME Flag value for the start method indicating that the resource should associate with a transaction where the association was suspended.
static int	TMSTARTRSCAN Flag value for the recover method indicating that the resource manager should start a new recovery scan.
static int	TMSUCCESS Flag value for the end method indicating that the transaction should be disassociated, and that the work has completed sucessfully.
static int	TMSUSPEND Flag value for the end method indicating that the resource should temporarily suspend the association with the transaction.
static int	XA_OK Value returned from the prepare method to indicate that the resource has successfully prepared to commit the transaction.
static int	XA_RDONLY Value returned from the prepare method to indicate that the resource was not changed in this transaction.

Method Summary

Methods

Modifier and Type	Method and Description
void	commit(Xid xid, boolean onePhase) Commit the work done on this resource in the given transaction.
void	end(Xid xid, int flags) Called to disassociate the resource from a transaction.
void	forget(Xid xid) Tells the resource manager to forget about a heuristic decision.
int	getTransactionTimeout() Get the current transaction timeout value for this resource.
boolean	isSameRM(XAResource xaRes) Tells the caller if this resource has the same resource manager as the argument resource.
int	prepare(Xid xid) Prepare to commit the work done on this resource in the given transaction.
Xid[]	recover(int flag) Return a list of transactions that are in a prepared or heuristically state.
void	rollback(Xid xid) Roll back the work done on this resource in the given transaction.
boolean	setTransactionTimeout(int seconds) Set the transaction timeout value for this resource.
void	start(Xid xid, int flags) Called to associate the resource with a transaction.

Field Detail

TMNOFLAGS

static final int TMNOFLAGS

Flag value indicating that no flags are set.

See Also:

Constant Field Values

TMONEPHASE

static final int TMONEPHASE

JTA specifies this constant and states that it indicates that the caller is using one-phase optimization, but this constant seems not to be used by JTA.

See Also:

Constant Field Values

TMJOIN

static final int TMJOIN

Flag value for the start method indicating that the resource should associate with a transaction previously seen by this resource manager.

See Also:

Constant Field Values

TMRESUME

static final int TMRESUME

Flag value for the start method indicating that the resource should associate with a transaction where the association was suspended.

See Also:

Constant Field Values

TMSUCCESS

static final int TMSUCCESS

Flag value for the end method indicating that the transaction should be disassociated, and that the work has completed sucessfully.

See Also:

Constant Field Values

TMFAIL

static final int TMFAIL

Flag value for the end method indicating that the transaction should be disassociated, and that the work has failed

See Also:

Constant Field Values

TMSUSPEND

static final int TMSUSPEND

Flag value for the end method indicating that the resource should temporarily suspend the association with the transaction.

See Also:

Constant Field Values

XA_RDONLY

static final int XA_RDONLY

Value returned from the prepare method to indicate that the resource was not changed in this transaction.

See Also:

Constant Field Values

XA_OK

static final int XA_OK

Value returned from the prepare method to indicate that the resource has successfully prepared to commit the transaction.

See Also:

Constant Field Values

TMSTARTRSCAN

static final int TMSTARTRSCAN

Flag value for the recover method indicating that the resource manager should start a new recovery scan.

See Also:

Constant Field Values

TMENDRSCAN

static final int TMENDRSCAN

Flag value for the recover method indicating that the resource manager should end the current recovery scan.

See Also:

Constant Field Values

Method Detail

start

void start(Xid xid,
         int flags)
           throws XAException

Called to associate the resource with a transaction. If the flags argument is TMNOFLAGS, the transaction must not previously have been seen by this resource manager, or an XAException with error code XAER_DUPID will be thrown. If the flags argument is TMJOIN, the resource will join a transaction previously seen by tis resource manager. If the flags argument is TMRESUME the resource will resume the transaction association that was suspended with end(TMSUSPEND).

Parameters:

xid - The id of the transaction to associate with.

flags - Must be either TMNOFLAGS, TMJOIN or TMRESUME.

Throws:

XAException - If an error occurred.

end

void end(Xid xid,
       int flags)
         throws XAException

Called to disassociate the resource from a transaction. If the flags argument is TMSUCCESS, the portion of work was done sucessfully. If the flags argument is TMFAIL, the portion of work failed. The resource manager may mark the transaction for rollback only to avoid the transaction being committed. If the flags argument is TMSUSPEND the resource will temporarily suspend the transaction association. The transaction must later be re-associated by giving the TMRESUME flag to the start method.

Parameters:

xid - The id of the transaction to disassociate from.

flags - Must be either TMSUCCESS, TMFAIL or TMSUSPEND.

Throws:

XAException - If an error occurred.

prepare

int prepare(Xid xid)
            throws XAException

Prepare to commit the work done on this resource in the given transaction. This method cannot return a status indicating that the transaction should be rolled back. If the resource wants the transaction to be rolled back, it should throw an XAException at the caller.

Parameters:

xid - The id of the transaction to prepare to commit work for.

Returns:

Either XA_OK or XA_RDONLY.

Throws:

XAException - If an error occurred.

commit

void commit(Xid xid,
          boolean onePhase)
            throws XAException

Commit the work done on this resource in the given transaction. If the onePhase argument is true, one-phase optimization is being used, and the prepare method must not have been called for this transaction. Otherwise, this is the second phase of the two-phase commit protocol.

Parameters:

xid - The id of the transaction to commit work for.

onePhase - If true, the transaction manager is using one-phase optimization.

Throws:

XAException - If an error occurred.

rollback

void rollback(Xid xid)
              throws XAException

Roll back the work done on this resource in the given transaction.

Parameters:

xid - The id of the transaction to commit work for.

Throws:

XAException - If an error occurred.

forget

void forget(Xid xid)
            throws XAException

Tells the resource manager to forget about a heuristic decision.

Parameters:

xid - The id of the transaction that was ended with a heuristic decision.

Throws:

XAException - If an error occurred.

recover

Xid[] recover(int flag)
              throws XAException

Return a list of transactions that are in a prepared or heuristically state. This method looks not only at the resource it is invoked on, but also on all other resources managed by the same resource manager. It is intended to be used by the application server when recovering after a server crash.

A recovery scan is done with one or more calls to this method. At the first call, TMSTARTRSCAN must be in the flag argument to indicate that the scan should be started. During the recovery scan, the resource manager maintains an internal cursor that keeps track of the progress of the recovery scan. To end the recovery scan, the TMENDRSCAN must be passed in the flag argument.

Parameters:

flag - Must be either TMNOFLAGS, TMSTARTRSCAN, TMENDRSCAN or TMSTARTRSCAN|TMENDRSCAN.

Returns:

An array of zero or more transaction ids.

Throws:

XAException - If an error occurred.

isSameRM

boolean isSameRM(XAResource xaRes)
                 throws XAException

Tells the caller if this resource has the same resource manager as the argument resource. The transaction manager needs this method to be able to decide if the start method should be given the TMJOIN flag.

Throws:

XAException - If an error occurred.

getTransactionTimeout

int getTransactionTimeout()
                          throws XAException

Get the current transaction timeout value for this resource.

Returns:

The current timeout value, in seconds.

Throws:

XAException - If an error occurred.

setTransactionTimeout

boolean setTransactionTimeout(int seconds)
                              throws XAException

Set the transaction timeout value for this resource. If the seconds argument is 0, the timeout value is set to the default timeout value of the resource manager. Not all resource managers support setting the timeout value. If the resource manager does not support setting the timeout value, it should return false.

Parameters:

seconds - The timeout value, in seconds.

Returns:

True if the timeout value could be set, otherwise false.

Throws:

XAException - If an error occurred.