Package oracle.jdbc.xa.client

Class OracleXAResource

java.lang.Object

oracle.jdbc.xa.OracleXAResource

oracle.jdbc.xa.client.OracleXAResource

All Implemented Interfaces:

XAResource, oracle.jdbc.diagnostics.Diagnosable, oracle.jdbc.diagnostics.PropertyChangeListener, oracle.jdbc.internal.Monitor

Direct Known Subclasses:

OracleXAHeteroResource

public class OracleXAResource
extends OracleXAResource

Implements javax.transaction.xa.XAResource.

Nested Class Summary

Nested classes/interfaces inherited from interface oracle.jdbc.internal.Monitor

oracle.jdbc.internal.Monitor.CloseableLock, oracle.jdbc.internal.Monitor.WaitableMonitor

Field Summary

Fields inherited from class oracle.jdbc.xa.OracleXAResource

activeXid, canBeMigratablySuspended, connection, dblink, DEFAULT_XA_TIMEOUT, ORAISOLATIONMASK, ORATMREADONLY, ORATMREADWRITE, ORATMSERIALIZABLE, ORATRANSLOOSE, savedConnectionAutoCommit, savedXAConnectionAutoCommit, timeout, TMENDRSCAN, TMFAIL, TMJOIN, TMMIGRATE, TMNOFLAGS, TMNOMIGRATE, TMONEPHASE, TMPROMOTE, TMRESUME, TMSTARTRSCAN, TMSUCCESS, TMSUSPEND, XA_OK, xaconnection, xidHash

Fields inherited from interface javax.transaction.xa.XAResource

XA_RDONLY

Constructor Summary

Constructors

Constructor	Description
OracleXAResource()
OracleXAResource(Connection pm_conn, OracleXAConnection xaconn)

Method Summary

Modifier and Type	Method	Description
void	commit(Xid xid, boolean onePhase)	commit() -- Commit work done by global transaction specified by xid.
protected void	commitSessionlessTransaction(Xid xid)	Commit sessionless transaction when XAThroughSessionlessTransactions is enabled.
protected void	doCommit(Xid xid, boolean onePhase)
protected int	doDoTwoPhaseAction(int nsites, int action, String[] dbnames, Xid[] xids)
protected int	doEnd(Xid xid, int flag, boolean isLocallySuspended)
protected int	doForget(Xid xid)
protected int	doPrepare(Xid xid)
protected void	doRollback(Xid xid)
protected int	doStart(Xid xid, int flag)
void	doTwoPhaseAction(int nsites, int action, String[] dbnames, Xid[] xids)
void	end(Xid xid, int flag)	end()-- End work performed on behalf of a transaction branch.
protected void	endSessionlessTransaction(Xid xid)	Suspend sessionless transaction when XAThroughSessionlessTransactions is enabled.
void	forget(Xid xid)	forget() -- Tell RM to forget about a heuristically completed txn branch
int	prepare(Xid xid)	prepare() -- Ask RM to prepare for a commit of the txn specified in xid.
void	rollback(Xid xid)	rollback() -- Ask RM to roll back work done on behalf of a txn branch.
protected void	rollbackSessionlessTransaction(Xid xid)	Rollback sessionless transaction when XAThroughSessionlessTransactions is enabled.
void	start(Xid xid, int flag)	start() -- Starts work on behalf of a transaction branch.
protected void	startSessionlessTransaction(Xid xid, int flag)	Start/Resume sessionless transaction when XAThroughSessionlessTransactions is enabled.

Methods inherited from class oracle.jdbc.xa.OracleXAResource

allowGlobalTxnModeOnly, checkError, checkError, checkError, convertError, createOrUpdateXid, enterGlobalTxnMode, exitGlobalTxnMode, getConnectionDuringExceptionHandling, getDiagnosable, getMonitorLock, getPhysicalConnection, getTransactionTimeout, isOnStack, isSameRM, isXidListEmpty, isXidSuspended, recover, removeXidFromList, restoreAutoCommitModeForGlobalTransaction, restoreAutoCommitModeForSessionlessTransaction, resumeStacked, saveAndAlterAutoCommitModeForGlobalTransaction, saveAndAlterAutoCommitModeForSessionlessTransaction, setTransactionTimeout, suspendStacked, updateXidList

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface oracle.jdbc.diagnostics.Diagnosable

begin, beginCurrentSql, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debugp, end, endCurrentSql, format, isDebugEnabled, isDiagnoseFirstFailureEnabled, isLoggable, isSensitiveEnabled, onClose, propertyChange, resumeLogging, secure, suspendLogging, trace, tracep

Methods inherited from interface oracle.jdbc.internal.Monitor

acquireCloseableLock, acquireLock, assertLockHeldByCurrentThread, isReentrantLock, releaseLock

Constructor Details

OracleXAResource

public OracleXAResource()

OracleXAResource

public OracleXAResource(Connection pm_conn,
 OracleXAConnection xaconn)
                 throws XAException

Throws:

XAException

Method Details

startSessionlessTransaction

protected void startSessionlessTransaction(Xid xid,
 int flag)
                                    throws XAException

Start/Resume sessionless transaction when XAThroughSessionlessTransactions is enabled.

Parameters:

xid - the transaction id

flag - TMNOFLAGS, TMRESUME, TMJOIN

Throws:

XAException

endSessionlessTransaction

protected void endSessionlessTransaction(Xid xid)
                                  throws XAException

Suspend sessionless transaction when XAThroughSessionlessTransactions is enabled. These are cases where a program may call end() on a transaction that is different that the active one:

• Transaction does not exist
• Transaction is active in a different session
• Transaction was already ended or suspended

For XA there are a lot of things happening but in summary when a program is ending a transaction that is different from the active one, it will makes sure to suspend the active transaction and resume it again after dealing with the transaction passed as parameter. Now for the 3 cases this is what happens in XA:

• If transaction does not exist, the database throws an exception
• If the transaction is active in a different session, database will also throw an exception.
• If transaction has already been suspended or ended in a different session it is resumed first then ended. (I don't really know why it does that, it could just make it a no-op)

If we want to have the same behavior as XA we need to throw an exception for first two cases. But not doing so shouldn't be an issue when switching from using XA to sessionless transactions, so we might make it a no-op for all cases, especially when considering the fact that doing so would require 3 additional round-trips.

Parameters:

xid - the id of the transaction to be suspend

Throws:

XAException

commitSessionlessTransaction

protected void commitSessionlessTransaction(Xid xid)
                                     throws XAException

Commit sessionless transaction when XAThroughSessionlessTransactions is enabled.

Parameters:

xid - the transaction id

Throws:

XAException

rollbackSessionlessTransaction

protected void rollbackSessionlessTransaction(Xid xid)
                                       throws XAException

Rollback sessionless transaction when XAThroughSessionlessTransactions is enabled.

Parameters:

xid - the transaction id

Throws:

XAException

start

public void start(Xid xid,
 int flag)
           throws XAException

start() -- Starts work on behalf of a transaction branch. If TMJOIN is specified, the start is for joining an existing 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. start() allows Isolation flags to be set, only when beginning a new transaction. XAER_INVAL exception is raised for error cases, such as (1) when JOIN/RESUME specified on start (2) invalid Isol flag is set. The valid Isolation levels allowed are: ORATMREADONLY ORATMREADWRITE ORATMSERIALIZABLE

Specified by:

start in interface XAResource

Specified by:

start in class OracleXAResource

Parameters:

xid - A global transaction identifier.

flag - One of TMNOFLAGS, TMJOIN, TMNOMIGRATE 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.

doStart

protected int doStart(Xid xid,
 int flag)
               throws XAException,
SQLException

Throws:

XAException

SQLException

end

public void end(Xid xid,
 int flag)
         throws 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 suspended 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 XAResource

Specified by:

end in class OracleXAResource

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:

XAException - An error has occurred. Possible XAException values are XAER_RMERR, XAER_RMFAILED, XAER_NOTA, XAER_INVAL, XAER_PROTO, or XA_RB.

doEnd

protected int doEnd(Xid xid,
 int flag,
 boolean isLocallySuspended)
             throws XAException,
SQLException

Throws:

XAException

SQLException

commit

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

commit() -- Commit work done by global transaction specified by xid.

Specified by:

commit in interface XAResource

Specified by:

commit in class OracleXAResource

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:

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 parameter 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.

doCommit

protected void doCommit(Xid xid,
 boolean onePhase)
                 throws XAException,
SQLException

Throws:

XAException

SQLException

prepare

public int prepare(Xid xid)
            throws XAException

prepare() -- Ask RM to prepare for a commit of the txn specified in xid.

Specified by:

prepare in interface XAResource

Specified by:

prepare in class OracleXAResource

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:

XAException - (An error has occurred.) Possible exception values are: XA_RB, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

doPrepare

protected int doPrepare(Xid xid)
                 throws XAException,
SQLException

Throws:

XAException

SQLException

forget

public void forget(Xid xid)
            throws XAException

forget() -- Tell RM to forget about a heuristically completed txn branch

Specified by:

forget in interface XAResource

Specified by:

forget in class OracleXAResource

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.

doForget

protected int doForget(Xid xid)
                throws XAException,
SQLException

Throws:

XAException

SQLException

rollback

public void rollback(Xid xid)
              throws XAException

rollback() -- Ask RM to roll back work done on behalf of a txn branch.

Specified by:

rollback in interface XAResource

Specified by:

rollback in class OracleXAResource

Parameters:

xid - A global transaction identifier.

Throws:

XAException - An error has occurred.

doRollback

protected void doRollback(Xid xid)
                   throws XAException,
SQLException

Throws:

XAException

SQLException

doTwoPhaseAction

public void doTwoPhaseAction(int nsites,
 int action,
 String[] dbnames,
 Xid[] xids)
                      throws XAException

Throws:

XAException

doDoTwoPhaseAction

protected int doDoTwoPhaseAction(int nsites,
 int action,
 String[] dbnames,
 Xid[] xids)
                          throws XAException

Throws:

XAException