| javax.transaction.xa.XAResource
| XAResource | | public interface XAResource (Code) | | 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
XAResource.start(Xid,int) start method to associate the
global transaction with the resource, and it uses the
XAResource.end(Xid,int) 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
XAResource.isSameRM(XAResource) method can be used.
version:
$Revision: 57196 $ |
| Field Summary | |
| final public static int | TMENDRSCAN
Flag value for the
XAResource.recover(int) recover method indicating
that the resource manager should end the current recovery scan. | | final public static int | TMFAIL
| | final public static int | TMJOIN
Flag value for the
XAResource.start(Xid,int) start method indicating
that the resource should associate with a transaction previously seen
by this resource manager. | | final public static int | TMNOFLAGS
Flag value indicating that no flags are set. | | final public 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. | | final public static int | TMRESUME
Flag value for the
XAResource.start(Xid,int) start method indicating
that the resource should associate with a transaction where the
association was suspended. | | final public static int | TMSTARTRSCAN
Flag value for the
XAResource.recover(int) recover method indicating
that the resource manager should start a new recovery scan. | | final public static int | TMSUCCESS
Flag value for the
XAResource.end(Xid,int) end method indicating that
the transaction should be disassociated, and that the work has
completed sucessfully. | | final public static int | TMSUSPEND
Flag value for the
XAResource.end(Xid,int) end method indicating that
the resource should temporarily suspend the association with the
transaction. | | final public static int | XA_OK
Value returned from the
XAResource.prepare(Xid) prepare method to
indicate that the resource has successfully prepared to commit
the transaction. | | final public static int | XA_RDONLY
Value returned from the
XAResource.prepare(Xid) prepare method to
indicate that the resource was not changed in this transaction. |
| Method Summary | |
| public void | commit(Xid xid, boolean onePhase)
Commit the work done on this resource in the given transaction. | | public void | end(Xid xid, int flags)
Called to disassociate the resource from a transaction.
If the flags argument is
XAResource.TMSUCCESS , the portion of work
was done sucessfully.
If the flags argument is
XAResource.TMFAIL , the portion of work
failed. | | public void | forget(Xid xid)
Tells the resource manager to forget about a heuristic decision. | | public int | getTransactionTimeout()
Get the current transaction timeout value for this resource. | | public boolean | isSameRM(XAResource xaRes)
Tells the caller if this resource has the same resource manager
as the argument resource. | | public int | prepare(Xid xid)
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. | | public Xid[] | recover(int flag)
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,
XAResource.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
XAResource.TMENDRSCAN must be passed
in the flag argument.
Parameters:
flag - Must be either XAResource.TMNOFLAGS, XAResource.TMSTARTRSCAN,XAResource.TMENDRSCAN or TMSTARTRSCAN|TMENDRSCAN. | | public void | rollback(Xid xid)
Roll back the work done on this resource in the given transaction. | | public boolean | setTransactionTimeout(int seconds)
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. | | public void | start(Xid xid, int flags)
Called to associate the resource with a transaction. |
| TMENDRSCAN | | final public static int TMENDRSCAN(Code) | | Flag value for the
XAResource.recover(int) recover method indicating
that the resource manager should end the current recovery scan.
|
| TMFAIL | | final public static int TMFAIL(Code) | | Flag value for the
XAResource.end(Xid,int) end method indicating that
the transaction should be disassociated, and that the work has
failed
|
| TMJOIN | | final public static int TMJOIN(Code) | | Flag value for the
XAResource.start(Xid,int) start method indicating
that the resource should associate with a transaction previously seen
by this resource manager.
|
| TMNOFLAGS | | final public static int TMNOFLAGS(Code) | | Flag value indicating that no flags are set.
|
| TMONEPHASE | | final public static int TMONEPHASE(Code) | | 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.
|
| TMRESUME | | final public static int TMRESUME(Code) | | Flag value for the
XAResource.start(Xid,int) start method indicating
that the resource should associate with a transaction where the
association was suspended.
|
| TMSTARTRSCAN | | final public static int TMSTARTRSCAN(Code) | | Flag value for the
XAResource.recover(int) recover method indicating
that the resource manager should start a new recovery scan.
|
| TMSUCCESS | | final public static int TMSUCCESS(Code) | | Flag value for the
XAResource.end(Xid,int) end method indicating that
the transaction should be disassociated, and that the work has
completed sucessfully.
|
| TMSUSPEND | | final public static int TMSUSPEND(Code) | | Flag value for the
XAResource.end(Xid,int) end method indicating that
the resource should temporarily suspend the association with the
transaction.
|
| XA_OK | | final public static int XA_OK(Code) | | Value returned from the
XAResource.prepare(Xid) prepare method to
indicate that the resource has successfully prepared to commit
the transaction.
|
| XA_RDONLY | | final public static int XA_RDONLY(Code) | | Value returned from the
XAResource.prepare(Xid) prepare method to
indicate that the resource was not changed in this transaction.
|
| commit | | public void commit(Xid xid, boolean onePhase) throws XAException(Code) | | 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
XAResource.prepare(Xid) 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.
Parameters:
onePhase - If true, the transaction manager is using one-phaseoptimization.
throws:
XAException - If an error occurred. |
| forget | | public void forget(Xid xid) throws XAException(Code) | | Tells the resource manager to forget about a heuristic decision.
Parameters:
xid - The id of the transaction that was ended with a heuristicdecision.
throws:
XAException - If an error occurred. |
| getTransactionTimeout | | public int getTransactionTimeout() throws XAException(Code) | | Get the current transaction timeout value for this resource.
The current timeout value, in seconds.
throws:
XAException - If an error occurred. |
| prepare | | public int prepare(Xid xid) throws XAException(Code) | | 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. Either XAResource.XA_OK or XAResource.XA_RDONLY.
throws:
XAException - If an error occurred. |
| recover | | public Xid[] recover(int flag) throws XAException(Code) | | 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,
XAResource.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
XAResource.TMENDRSCAN must be passed
in the flag argument.
Parameters:
flag - Must be either XAResource.TMNOFLAGS, XAResource.TMSTARTRSCAN,XAResource.TMENDRSCAN or TMSTARTRSCAN|TMENDRSCAN. An array of zero or more transaction ids.
throws:
XAException - If an error occurred. |
| rollback | | public void rollback(Xid xid) throws XAException(Code) | | 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. |
| setTransactionTimeout | | public boolean setTransactionTimeout(int seconds) throws XAException(Code) | | 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. True if the timeout value could be set, otherwise false.
throws:
XAException - If an error occurred. |
| start | | public void start(Xid xid, int flags) throws XAException(Code) | | Called to associate the resource with a transaction.
If the flags argument is
XAResource.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
XAResource.TMJOIN , the resource will join a
transaction previously seen by tis resource manager.
If the flags argument is
XAResource.TMRESUME the resource will
resume the transaction association that was suspended with
end(TMSUSPEND).
Parameters:
xid - The id of the transaction to associate with.
Parameters:
flags - Must be either XAResource.TMNOFLAGS, XAResource.TMJOINor XAResource.TMRESUME.
throws:
XAException - If an error occurred. |
|
|