public interface XAResource
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.
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. |
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.
|
static final int TMNOFLAGS
static final int TMONEPHASE
static final int TMJOIN
start
method indicating
that the resource should associate with a transaction previously seen
by this resource manager.static final int TMRESUME
start
method indicating
that the resource should associate with a transaction where the
association was suspended.static final int TMSUCCESS
end
method indicating that
the transaction should be disassociated, and that the work has
completed sucessfully.static final int TMFAIL
end
method indicating that
the transaction should be disassociated, and that the work has
failedstatic final int TMSUSPEND
end
method indicating that
the resource should temporarily suspend the association with the
transaction.static final int XA_RDONLY
prepare
method to
indicate that the resource was not changed in this transaction.static final int XA_OK
prepare
method to
indicate that the resource has successfully prepared to commit
the transaction.static final int TMSTARTRSCAN
recover
method indicating
that the resource manager should start a new recovery scan.static final int TMENDRSCAN
recover
method indicating
that the resource manager should end the current recovery scan.void start(Xid xid, int flags) throws XAException
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).xid
- The id of the transaction to associate with.flags
- Must be either TMNOFLAGS
, TMJOIN
or TMRESUME
.XAException
- If an error occurred.void end(Xid xid, int flags) throws XAException
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.xid
- The id of the transaction to disassociate from.flags
- Must be either TMSUCCESS
, TMFAIL
or TMSUSPEND
.XAException
- If an error occurred.int prepare(Xid xid) throws XAException
XAException
at the
caller.xid
- The id of the transaction to prepare to commit work for.XA_OK
or XA_RDONLY
.XAException
- If an error occurred.void commit(Xid xid, boolean onePhase) throws XAException
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.xid
- The id of the transaction to commit work for.onePhase
- If true, the transaction manager is using one-phase
optimization.XAException
- If an error occurred.void rollback(Xid xid) throws XAException
xid
- The id of the transaction to commit work for.XAException
- If an error occurred.void forget(Xid xid) throws XAException
xid
- The id of the transaction that was ended with a heuristic
decision.XAException
- If an error occurred.Xid[] recover(int flag) throws XAException
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.
flag
- Must be either TMNOFLAGS
, TMSTARTRSCAN
,
TMENDRSCAN
or TMSTARTRSCAN|TMENDRSCAN
.XAException
- If an error occurred.boolean isSameRM(XAResource xaRes) throws XAException
start
method should be given the
TMJOIN
flag.XAException
- If an error occurred.int getTransactionTimeout() throws XAException
XAException
- If an error occurred.boolean setTransactionTimeout(int seconds) throws XAException
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.seconds
- The timeout value, in seconds.XAException
- If an error occurred.Copyright © 2017 JBoss by Red Hat. All rights reserved.