org.hsqldb.jdbc.pool
Class JDBCXAResource

java.lang.Object
  extended by org.hsqldb.jdbc.pool.JDBCXAResource
All Implemented Interfaces:
XAResource

public class JDBCXAResource
extends Object
implements XAResource

Used by a global transaction service to control HSQLDB transactions. Not for use by end-users. End manage global transactions using transaction APIs such as JTA.

According to section 12.3 of the JDBC 3.0 spec, there is a 1:1 correspondence between XAConnection and XAResource, and A given XAConnection object may be associated with at most one transaction at a time. Therefore, there may be at any time at most one transaction managed by a XAResource object. One implication is, the XAResource can track the current transaction state with a scalar. Another implication is, the Xids for most of the XAResource interface methods just introduce unnecessary complexity and an unnecessary point of failure-- there can be only one transaction for this object, so why track another identifier for it. My strategy is to just "validate" that the Xid does not change within a transaction. Exceptions to this are the commit and rollback methods, which the JDBC spec says can operate against any XAResource instance from the same XADataSource. N.b. The JDBC Spec does not state whether the prepare and forget methods are XAResource-specific or XADataSource-specific.

Since:
2.0.0
Author:
Blaine Simpson (blaine dot simpson at admc dot com)
See Also:
XAResource

Field Summary
 
Fields inherited from interface javax.transaction.xa.XAResource
TMENDRSCAN, TMFAIL, TMJOIN, TMNOFLAGS, TMONEPHASE, TMRESUME, TMSTARTRSCAN, TMSUCCESS, TMSUSPEND, XA_OK, XA_RDONLY
 
Constructor Summary
JDBCXAResource(JDBCXADataSource xaDataSource, JDBCConnection connection)
          Constructs a resource using the given data source and connection.
 
Method Summary
 void commit(Xid xid, boolean onePhase)
          Per the JDBC 3.0 spec, this commits the transaction for the specified Xid, not necessarily for the transaction associated with this XAResource object.
 void commitThis(boolean onePhase)
          This commits the connection associated with this XAResource.
 void end(Xid xid, int flags)
           
 void forget(Xid xid)
          The XAResource API spec indicates implies that this is only for 2-phase transactions.
 int getTransactionTimeout()
           
 boolean isSameRM(XAResource xares)
          Stub.
 int prepare(Xid xid)
          Vote on whether to commit the global transaction.
 int prepareThis()
           
 Xid[] recover(int flag)
          Obtain a list of Xids of the current resource manager for XAResources currently in the 'prepared' * state.
 void rollback(Xid xid)
          Per the JDBC 3.0 spec, this rolls back the transaction for the specified Xid, not necessarily for the transaction associated with this XAResource object.
 void rollbackThis()
          This rolls back the connection associated with this XAResource.
 boolean setTransactionTimeout(int seconds)
           
 void start(Xid xid, int flags)
           
 boolean withinGlobalTransaction()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JDBCXAResource

public JDBCXAResource(JDBCXADataSource xaDataSource,
                      JDBCConnection connection)
Constructs a resource using the given data source and connection.

Parameters:
xaDataSource - JDBCXADataSource
connection - A non-wrapped JDBCConnection which we need in order to do real (non-wrapped) commits, rollbacks, etc. This is not for the end user. We need the real thing.
Method Detail

withinGlobalTransaction

public boolean withinGlobalTransaction()

commit

public void commit(Xid xid,
                   boolean onePhase)
            throws XAException
Per the JDBC 3.0 spec, this commits the transaction for the specified Xid, not necessarily for the transaction associated with this XAResource object.

Specified by:
commit in interface XAResource
Parameters:
xid - Xid
onePhase - boolean
Throws:
XAException - on error

commitThis

public void commitThis(boolean onePhase)
                throws XAException
This commits the connection associated with this XAResource.

Parameters:
onePhase - boolean
Throws:
XAException - generically, since the more specific exceptions require a JTA API to compile.

end

public void end(Xid xid,
                int flags)
         throws XAException
Specified by:
end in interface XAResource
Throws:
XAException

forget

public void forget(Xid xid)
            throws XAException
The XAResource API spec indicates implies that this is only for 2-phase transactions. I guess that one-phase transactions need to call rollback() to abort. I think we want this JDBCXAResource instance to be garbage-collectable after (a) this method is called, and (b) the tx manager releases its handle to it.

Specified by:
forget in interface XAResource
Parameters:
xid - Xid
Throws:
XAException - on error
See Also:
XAResource.forget(Xid)

getTransactionTimeout

public int getTransactionTimeout()
                          throws XAException
Specified by:
getTransactionTimeout in interface XAResource
Returns:
int
Throws:
XAException - on error

isSameRM

public boolean isSameRM(XAResource xares)
                 throws XAException
Stub. See implementation comment in the method for why this is not implemented yet.

Specified by:
isSameRM in interface XAResource
Parameters:
xares - XAResource
Returns:
false.
Throws:
XAException - on error

prepare

public int prepare(Xid xid)
            throws XAException
Vote on whether to commit the global transaction. We assume Xid may be different from this, as in commit() method.

Specified by:
prepare in interface XAResource
Parameters:
xid - Xid
Returns:
commitType of XA_RDONLY or XA_OK. (Actually only XA_OK now).
Throws:
XAException - to vote negative.

prepareThis

public int prepareThis()
                throws XAException
Throws:
XAException

recover

public Xid[] recover(int flag)
              throws XAException
Obtain a list of Xids of the current resource manager for XAResources currently in the 'prepared' * state. According to the JDBC 3.0 spec, the Xids of a specific resource manager are those of the same XADataSource.

Specified by:
recover in interface XAResource
Parameters:
flag - int
Returns:
Xid[]
Throws:
XAException - on error

rollback

public void rollback(Xid xid)
              throws XAException
Per the JDBC 3.0 spec, this rolls back the transaction for the specified Xid, not necessarily for the transaction associated with this XAResource object.

Specified by:
rollback in interface XAResource
Parameters:
xid - Xid
Throws:
XAException - on error

rollbackThis

public void rollbackThis()
                  throws XAException
This rolls back the connection associated with this XAResource.

Throws:
XAException - generically, since the more specific exceptions require a JTA API to compile.

setTransactionTimeout

public boolean setTransactionTimeout(int seconds)
                              throws XAException
Specified by:
setTransactionTimeout in interface XAResource
Parameters:
seconds - int
Returns:
boolean
Throws:
XAException - on error

start

public void start(Xid xid,
                  int flags)
           throws XAException
Specified by:
start in interface XAResource
Throws:
XAException


Copyright © 2001 - 2017 HSQL Development Group.