javax.transaction.xa
Interface XAResource

All Known Implementing Classes:

Resource (src) , SpyXAResource (src) , TestManagedConnection (src) , TestResourceAdapterTxInflow.TestWork (src) , TestXAResource (src) , XAManagedConnection (src)

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.

TMNOFLAGS

public static final int TMNOFLAGS

Flag value indicating that no flags are set.

See Also:

Constant Field Values (src)

TMONEPHASE

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

TMJOIN

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

TMRESUME

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

TMSUCCESS

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

TMFAIL

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

TMSUSPEND

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

XA_RDONLY

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

XA_OK

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

TMSTARTRSCAN

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

TMENDRSCAN

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

start

public void start(Xid (src)  xid,
                  int flags)
           throws XAException (src) 

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 (src) 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 (src) - If an error occurred.

end

public void end(Xid (src)  xid,
                int flags)
         throws XAException (src) 

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 (src) - If an error occurred.

prepare

public int prepare(Xid (src)  xid)
            throws XAException (src) 

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 (src) - If an error occurred.

commit

public void commit(Xid (src)  xid,
                   boolean onePhase)
            throws XAException (src) 

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 (src) - If an error occurred.

rollback

public void rollback(Xid (src)  xid)
              throws XAException (src) 

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 (src) - If an error occurred.

forget

public void forget(Xid (src)  xid)
            throws XAException (src) 

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 (src) - If an error occurred.

recover

public Xid (src) [] recover(int flag)
              throws XAException (src) 

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 (src) - If an error occurred.

isSameRM

public boolean isSameRM(XAResource (src)  xaRes)
                 throws XAException (src) 

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 (src) - If an error occurred.

getTransactionTimeout

public int getTransactionTimeout()
                          throws XAException (src) 

Get the current transaction timeout value for this resource.

Returns:

The current timeout value, in seconds.

Throws:

XAException (src) - If an error occurred.

setTransactionTimeout

public boolean setTransactionTimeout(int seconds)
                              throws XAException (src) 

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 (src) - If an error occurred.