Oracle JDBC API Reference
11g Release 2 ("11.2.0.3.0")

oracle.jdbc.xa
Class OracleXAResource

java.lang.Object
  extended by oracle.jdbc.xa.OracleXAResource
All Implemented Interfaces:
javax.transaction.xa.XAResource
Direct Known Subclasses:
OracleXAResource

public abstract class OracleXAResource
extends java.lang.Object
implements javax.transaction.xa.XAResource

An Oracle XA Resource.


Field Summary
static java.lang.String BUILD_DATE
           
static short DEFAULT_XA_TIMEOUT
           
static int ORAISOLATIONMASK
           
static int ORATMREADONLY
           
static int ORATMREADWRITE
           
static int ORATMSERIALIZABLE
           
static int ORATRANSLOOSE
           
static int TMENDRSCAN
           
static int TMFAIL
           
static int TMJOIN
           
static int TMMIGRATE
           
static int TMNOFLAGS
           
static int TMNOMIGRATE
           
static int TMONEPHASE
           
static int TMRESUME
           
static int TMSTARTRSCAN
           
static int TMSUCCESS
           
static int TMSUSPEND
           
static boolean TRACE
           
static int XA_OK
           
 
Fields inherited from interface javax.transaction.xa.XAResource
XA_RDONLY
 
Constructor Summary
OracleXAResource()
           
OracleXAResource(java.sql.Connection pm_conn, OracleXAConnection xaconn)
          OracleXAResource() -- The initializer.
 
Method Summary
abstract  void commit(javax.transaction.xa.Xid xid, boolean onePhase)
          commit() -- Commit work done by global transaction specified by xid.
abstract  void end(javax.transaction.xa.Xid xid, int flag)
          end()-- End work performed on behalf of a transaction branch.
abstract  void forget(javax.transaction.xa.Xid xid)
          forget() -- Tell RM to forget about a heuristically completed txn branch
 int getTransactionTimeout()
          Obtain the current transaction timeout value set for this XAResource instance.
 boolean isSameRM(javax.transaction.xa.XAResource xares)
          This method is called to determine if the resource manager instance represented by the target object is the same as the resouce manager instance represented by the parameter xares.
abstract  int prepare(javax.transaction.xa.Xid xid)
          prepare() -- Ask RM to prepare for a commit of the txn specified in xid.
 javax.transaction.xa.Xid[] recover(int flag)
          Obtain a list of prepared transaction branches from a resource manager.
abstract  void rollback(javax.transaction.xa.Xid xid)
          rollback() -- Ask RM to roll back work done on behalf of a txn branch.
 boolean setTransactionTimeout(int seconds)
          Set the current transaction timeout value for this XAResource instance.
abstract  void start(javax.transaction.xa.Xid xid, int flag)
          start() -- Starts work on behalf of a transaction branch.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

XA_OK

public static final int XA_OK
See Also:
Constant Field Values

DEFAULT_XA_TIMEOUT

public static final short DEFAULT_XA_TIMEOUT
See Also:
Constant Field Values

TMNOFLAGS

public static final int TMNOFLAGS
See Also:
Constant Field Values

TMNOMIGRATE

public static final int TMNOMIGRATE
See Also:
Constant Field Values

TMENDRSCAN

public static final int TMENDRSCAN
See Also:
Constant Field Values

TMFAIL

public static final int TMFAIL
See Also:
Constant Field Values

TMMIGRATE

public static final int TMMIGRATE
See Also:
Constant Field Values

TMJOIN

public static final int TMJOIN
See Also:
Constant Field Values

TMONEPHASE

public static final int TMONEPHASE
See Also:
Constant Field Values

TMRESUME

public static final int TMRESUME
See Also:
Constant Field Values

TMSTARTRSCAN

public static final int TMSTARTRSCAN
See Also:
Constant Field Values

TMSUCCESS

public static final int TMSUCCESS
See Also:
Constant Field Values

TMSUSPEND

public static final int TMSUSPEND
See Also:
Constant Field Values

ORATMREADONLY

public static final int ORATMREADONLY
See Also:
Constant Field Values

ORATMREADWRITE

public static final int ORATMREADWRITE
See Also:
Constant Field Values

ORATMSERIALIZABLE

public static final int ORATMSERIALIZABLE
See Also:
Constant Field Values

ORAISOLATIONMASK

public static final int ORAISOLATIONMASK
See Also:
Constant Field Values

ORATRANSLOOSE

public static final int ORATRANSLOOSE
See Also:
Constant Field Values

BUILD_DATE

public static final java.lang.String BUILD_DATE
See Also:
Constant Field Values

TRACE

public static final boolean TRACE
See Also:
Constant Field Values
Constructor Detail

OracleXAResource

public OracleXAResource()

OracleXAResource

public OracleXAResource(java.sql.Connection pm_conn,
                        OracleXAConnection xaconn)
                 throws javax.transaction.xa.XAException
OracleXAResource() -- The initializer.

Throws:
javax.transaction.xa.XAException - throws an exception if the connection object is null.
Method Detail

start

public abstract void start(javax.transaction.xa.Xid xid,
                           int flag)
                    throws javax.transaction.xa.XAException
start() -- Starts work on behalf of a transaction branch. If TMJOIN is specified, the start is for joining an exisiting txn branch xid. If TMRESUME is specified, the start is to resume a suspended transaction branch specified in xid. Transaction suspend is done by calling the end method specifying the TMSUSPEND flag. If neither TMJOIN nor TMRESUME is specified and the transaction branch specified in xid already exists, the resource manager raises the duplicate transaction exception via XAER_DUPID.

Specified by:
start in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier.
Throws:
javax.transaction.xa.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.

end

public abstract void end(javax.transaction.xa.Xid xid,
                         int flag)
                  throws javax.transaction.xa.XAException
end()-- End 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 flag, the txn branch is temporarily suspended in incomplete state. The txn 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 RM 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.
flag - One of TMSUCCESS, TMFAIL, or TMSUSPEND.
Throws:
javax.transaction.xa.XAException - An error has occurred. Possible XAException values are XAER_RMERR, XAER_RMFAILED, XAER_NOTA, XAER_INVAL, XAER_PROTO, or XA_RB.

commit

public abstract void commit(javax.transaction.xa.Xid xid,
                            boolean onePhase)
                     throws javax.transaction.xa.XAException
commit() -- Commit work done by global transaction specified by xid.

Specified by:
commit in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier.
onePhase - If true, the RM should use a 1-phase commit protocol to commit the work done on behalf of xid.
Throws:
javax.transaction.xa.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 txn and the paramether onePhase is set to true, the RM may raise one of the XA_RB exceptions. Upon return, the RM has rolled back the branch's work and has released all held resources.

prepare

public abstract int prepare(javax.transaction.xa.Xid xid)
                     throws javax.transaction.xa.XAException
prepare() -- Ask RM to prepare for a commit of the txn 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 txn. The possible values are: XA_RDONLY or XA_OK. If the RM wants to roll back the transaction, it should do so by raising an appropriate XAException in the prepare method.
Throws:
javax.transaction.xa.XAException - (An error has occurred.) Possible exception values are: XA_RB, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

forget

public abstract void forget(javax.transaction.xa.Xid xid)
                     throws javax.transaction.xa.XAException
forget() -- Tell RM to forget about a heuristically completed txn branch

Specified by:
forget in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier.
Throws:
javax.transaction.xa.XAException - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

rollback

public abstract void rollback(javax.transaction.xa.Xid xid)
                       throws javax.transaction.xa.XAException
rollback() -- Ask RM to roll back work done on behalf of a txn branch.

Specified by:
rollback in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier.
Throws:
javax.transaction.xa.XAException - An error has occurred.

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. JDBC has been returning a complete list of prepared transaction branches when recover(flag) is called regardless which flag (TMNOFLAGS or TMSTARTRSCAN or TMENDRSCAN) is set. Beginning in 11.2.0.2, JDBC will do the following in order to accommodate certain TMs way of handling the recovery scan:

Example 1:

      MyXid[] xids = 
         xaRes.recover(XAResource.TMSTARTRSCAN | XAResource.TMENDRSCAN);
      for (int i=0; xids != null && i < xids.length; i++) {
      try {
         xaRes.rollback(xids[i]);
      ...
     

Example 2:

      MyXid[] xids = xaRes.recover(XAResource.TMSTARTRSCAN);
      while( xids!=null && xids.length>0)
      {
         for (int i=0; i < xids.length; i++) {
         try {
            xaRes.rollback(xids[i]);
            ...
            xids = xaRes.recover(XAResource.TMNOFLAG);
      }
      xaRes.recover(XAResource.TMENDRSCAN);
     

Example 3:

      MyXid[] xids = xaRes.recover(XAResource.TMNOFLAG);
      for (int i=0; xids != null && i < xids.length; i++) {
      try {
         xaRes.rollback(xids[i]);
      ...
      

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:
javax.transaction.xa.XAException - An error has occurred. Possible values are XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.

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 fo 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:
javax.transaction.xa.XAException - - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL.

isSameRM

public boolean isSameRM(javax.transaction.xa.XAResource xares)
                 throws javax.transaction.xa.XAException
This method is called to determine if the resource manager instance represented by the target object is the same as the resouce manager instance represented by the parameter xares.

Specified by:
isSameRM in interface javax.transaction.xa.XAResource
Parameters:
xares - - An XAResource object whose resource manager instance is to be compared with the resource manager instance of the target object.
Returns:
true if it's the same RM instance; otherwise false.
Throws:
javax.transaction.xa.XAException - - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL.

setTransactionTimeout

public boolean setTransactionTimeout(int seconds)
                              throws javax.transaction.xa.XAException
Set the current transaction timeout value for this XAResource instance. Once set, this timeout value is effective until setTransactionTimeout is invoked again with a different value. To reset the timeout value to the default value used by the resource manager, set the value to zero. If the timeout operation is performed successfully, the method returns true; otherwise false. If a resource manager does not support transaction timeout value to be set explicitly, this method returns false.

Specified by:
setTransactionTimeout in interface javax.transaction.xa.XAResource
Parameters:
seconds - - transaction timeout value in seconds.
Returns:
true if transaction timeout value is set successfully; otherwise false.
Throws:
javax.transaction.xa.XAException - - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.

Oracle JDBC API Reference
11g Release 2 ("11.2.0.3.0")

Copyright © 1998, 2007, Oracle. All rights reserved.