1.51.2

interbase.interclient
Class XAResource

java.lang.Object
  |
  +--interbase.interclient.XAResource

public class XAResource
extends Object
implements javax.transaction.xa.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. A JDBC driver or a JMS provider implements the XA 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 has a resource manager that is registered with the transaction manager. The transaction manager obtains an XAResource for each resource manager participating in a global transaction. It uses the start method to associate the global transaction with the XA resource, and it uses the end method to dissociate 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, these XA resource managers are informed by the transaction manager to prepare, commit, or rollback a transaction according to the two phase commit protocol.

Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported
Version:
Std Ext 0.7, JTA 0.9
See Also:
XAConnection, Xid

Field Summary
static int TMENDRSCAN
          End a recovery scan.
static int TMFAIL
          Dissociates the caller and mark the transaction branch rollback-only.
static int TMJOIN
          Caller is joining existing transaction branch.
static int TMNOFLAG
          Use TMNOFLAG to indicate no flags value is selected.
static int TMONEPHASE
          Caller is using one-phase optimization.
static int TMRESUME
          Caller is resuming association with with suspended transaction branch.
static int TMSTARTRSCAN
          Start a recovery scan.
static int TMSUCCESS
          Dissociate caller from transaction branch.
static int TMSUSPEND
          Caller is suspending (not ending) association with transaction branch.
 
Constructor Summary
XAResource()
           
 
Method Summary
 void commit(javax.transaction.xa.Xid xid, boolean onePhase)
          Commit the global transaction specified by xid.
 void end(javax.transaction.xa.Xid xid, int flags)
          Ends the work performed on behalf of a transaction branch.
 void forget(javax.transaction.xa.Xid xid)
          Tell the resource manager to forget about a heuristically completed transaction branch.
 int getTransactionTimeout()
          Obtain the current transaction timeout value set for this XAResource instance.
 int prepare(javax.transaction.xa.Xid xid)
          Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.
 javax.transaction.xa.Xid[] recover(int flag)
          Obtain a list of prepared transaction branches from a resource manager.
 void rollback(javax.transaction.xa.Xid xid)
          Inform the resource manager to roll back work done on behalf of a transaction branch
 void setTransactionTimeout(int seconds)
          Set the current transaction timeout value for this XAResource instance.
 void start(javax.transaction.xa.Xid xid, int flags)
          Start work on behalf of a transaction branch specified in xid
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TMENDRSCAN

public static final int TMENDRSCAN
End a recovery scan.

TMFAIL

public static final int TMFAIL
Dissociates the caller and mark the transaction branch rollback-only.

TMJOIN

public static final int TMJOIN
Caller is joining existing transaction branch.

TMNOFLAG

public static final int TMNOFLAG
Use TMNOFLAG to indicate no flags value is selected.

TMONEPHASE

public static final int TMONEPHASE
Caller is using one-phase optimization.

TMRESUME

public static final int TMRESUME
Caller is resuming association with with suspended transaction branch.

TMSTARTRSCAN

public static final int TMSTARTRSCAN
Start a recovery scan.

TMSUCCESS

public static final int TMSUCCESS
Dissociate caller from transaction branch.

TMSUSPEND

public static final int TMSUSPEND
Caller is suspending (not ending) association with transaction branch.
Constructor Detail

XAResource

public XAResource()
Method Detail

commit

public void commit(javax.transaction.xa.Xid xid,
                   boolean onePhase)
            throws javax.transaction.xa.XAException
Commit the global transaction specified by xid.
Specified by:
commit in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier
onePhase - If true, the resource manager should use a one-phase commit protocol to commit the work done on behalf of xid.
Throws:
XAException - An error has occurred. Possible XAExceptions are XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

If the resource manager did not commit the transaction and the paramether onePhase is set to true, the resource manager may raise one of the XA_RB* exceptions. Upon return, the resource manager has rolled back the branch's work and has released all held resources.

Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported

end

public void end(javax.transaction.xa.Xid xid,
                int flags)
         throws javax.transaction.xa.XAException
Ends the work performed on behalf of a transaction branch. The resource manager dissociates the XA resource from the transaction branch specified and let the transaction be completed. If TMSUSPEND is specified in flags, the transaction branch is temporarily suspended in incomplete state. The transaction context is in suspened state and must be resumed via start with TMRESUME specified. If TMFAIL is specified, the portion of work has failed. The resource manager may mark the transaction as rollback-only If TMSUCCESS is specified, the portion of work has completed successfully.
Specified by:
end in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier that is the same as what was used previously in the start method.
flags - One of TMSUCCESS, TMFAIL, or TMSUSPEND
Throws:
XAException - An error has occurred. Possible XAException values are XAER_RMERR, XAER_RMFAILED, XAER_NOTA, XAER_INVAL, XAER_PROTO, or XA_RB*.
Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported

forget

public void forget(javax.transaction.xa.Xid xid)
            throws javax.transaction.xa.XAException
Tell the resource manager to forget about a heuristically completed transaction branch.
Specified by:
forget in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier
Throws:
XAException - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.
Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported

getTransactionTimeout

public int getTransactionTimeout()
                          throws javax.transaction.xa.XAException
Obtain the current transaction timeout value set for this XAResource instance. If XAResource.setTransactionTimeout was not use prior to invoking this method, the return value is the default timeout set for the resource manager; otherwise, the value used in the previous setTransactionTimeout call is returned.
Specified by:
getTransactionTimeout in interface javax.transaction.xa.XAResource
Returns:
the transaction timeout value in seconds.
Throws:
XAException - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL.
Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported

prepare

public int prepare(javax.transaction.xa.Xid xid)
            throws javax.transaction.xa.XAException
Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.
Specified by:
prepare in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier
Returns:
A value indicating the resource manager's vote on the outcome of the transaction. The possible values are: XA_RDONLY or XA_OK. If the resource manager wants to roll back the transaction, it should do so by raising an appropriate XAException in the prepare method.
Throws:
XAException - An error has occurred. Possible exception values are: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.
Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported

recover

public javax.transaction.xa.Xid[] recover(int flag)
                                   throws javax.transaction.xa.XAException
Obtain a list of prepared transaction branches from a resource manager. The transaction manager calls this method during recovery to obtain the list of transaction branches that are currently in prepared or heuristically completed states.
Specified by:
recover in interface javax.transaction.xa.XAResource
Parameters:
flag - One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS must be used when no other flags are set in flags.
Returns:
The resource manager returns zero or more XIDs for the transaction branches that are currently in a prepared or heuristically completed state. If an error occurs during the operation, the resource manager should raise the appropriate XAException.
Throws:
XAException - An error has occurred. Possible values are XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.
Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported

rollback

public void rollback(javax.transaction.xa.Xid xid)
              throws javax.transaction.xa.XAException
Inform the resource manager to roll back work done on behalf of a transaction branch
Specified by:
rollback in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier
Throws:
XAException - An error has occurred
Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported

setTransactionTimeout

public void setTransactionTimeout(int seconds)
                           throws javax.transaction.xa.XAException
Set the current transaction timeout value for this XAResource instance. This value overwrites the default transaction timeout value in the resource manager. The newly assigned timeout value is effective for the life of this XAResource instance unless a new value is set.

Specified by:
setTransactionTimeout in interface javax.transaction.xa.XAResource
Parameters:
the - transaction timeout value in seconds.
Throws:
javax.transaction.xa.XAException - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.
Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported

start

public void start(javax.transaction.xa.Xid xid,
                  int flags)
           throws javax.transaction.xa.XAException
Start work on behalf of a transaction branch specified in xid
Specified by:
start in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier to be associated with the resource
flags - One of TMNOFLAGS, TMJOIN, or TMRESUME
Throws:
XAException - An error has occurred. Possible exceptions are XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE, XAER_NOTA, XAER_INVAL, or XAER_PROTO.
Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported

1.51.2

Send comments or suggestions to interclient@interbase.com