Module org.hsqldb

Class JDBCXAResource

java.lang.Object
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:
  • Constructor Details

    • 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 Details

    • 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
    • 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