Module org.hsqldb
Package org.hsqldb.jdbc.pool

Class JDBCXAResource

  • All Implemented Interfaces:
    javax.transaction.xa.XAResource
    public class JDBCXAResource
extends java.lang.Object
implements javax.transaction.xa.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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void commit​(javax.transaction.xa.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​(javax.transaction.xa.Xid xid, int flags)  
      void forget​(javax.transaction.xa.Xid xid)
      The XAResource API spec indicates implies that this is only for 2-phase transactions.
      int getTransactionTimeout()  
      boolean isSameRM​(javax.transaction.xa.XAResource xares)
      Stub.
      int prepare​(javax.transaction.xa.Xid xid)
      Vote on whether to commit the global transaction.
      int prepareThis()  
      javax.transaction.xa.Xid[] recover​(int flag)
      Obtain a list of Xids of the current resource manager for XAResources currently in the 'prepared' * state.
      void rollback​(javax.transaction.xa.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​(javax.transaction.xa.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​(javax.transaction.xa.Xid xid,
                   boolean onePhase)
            throws javax.transaction.xa.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 javax.transaction.xa.XAResource
        Parameters:
        xid - Xid
        onePhase - boolean
        Throws:
        javax.transaction.xa.XAException - on error

      • commitThis

        public void commitThis​(boolean onePhase)
                throws javax.transaction.xa.XAException
        This commits the connection associated with this XAResource.
        Parameters:
        onePhase - boolean
        Throws:
        javax.transaction.xa.XAException - generically, since the more specific exceptions require a JTA API to compile.

      • end

        public void end​(javax.transaction.xa.Xid xid,
                int flags)
         throws javax.transaction.xa.XAException
        Specified by:
        end in interface javax.transaction.xa.XAResource
        Throws:
        javax.transaction.xa.XAException

      • forget

        public void forget​(javax.transaction.xa.Xid xid)
            throws javax.transaction.xa.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 javax.transaction.xa.XAResource
        Parameters:
        xid - Xid
        Throws:
        javax.transaction.xa.XAException - on error

      • getTransactionTimeout

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

      • isSameRM

        public boolean isSameRM​(javax.transaction.xa.XAResource xares)
                 throws javax.transaction.xa.XAException
        Stub. See implementation comment in the method for why this is not implemented yet.
        Specified by:
        isSameRM in interface javax.transaction.xa.XAResource
        Parameters:
        xares - XAResource
        Returns:
        false.
        Throws:
        javax.transaction.xa.XAException - on error

      • prepare

        public int prepare​(javax.transaction.xa.Xid xid)
            throws javax.transaction.xa.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 javax.transaction.xa.XAResource
        Parameters:
        xid - Xid
        Returns:
        commitType of XA_RDONLY or XA_OK. (Actually only XA_OK now).
        Throws:
        javax.transaction.xa.XAException - to vote negative.

      • prepareThis

        public int prepareThis()
                throws javax.transaction.xa.XAException
        Throws:
        javax.transaction.xa.XAException

      • recover

        public javax.transaction.xa.Xid[] recover​(int flag)
                                   throws javax.transaction.xa.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 javax.transaction.xa.XAResource
        Parameters:
        flag - int
        Returns:
        Xid[]
        Throws:
        javax.transaction.xa.XAException - on error

      • rollback

        public void rollback​(javax.transaction.xa.Xid xid)
              throws javax.transaction.xa.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 javax.transaction.xa.XAResource
        Parameters:
        xid - Xid
        Throws:
        javax.transaction.xa.XAException - on error

      • rollbackThis

        public void rollbackThis()
                  throws javax.transaction.xa.XAException
        This rolls back the connection associated with this XAResource.
        Throws:
        javax.transaction.xa.XAException - generically, since the more specific exceptions require a JTA API to compile.

      • setTransactionTimeout

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

      • start

        public void start​(javax.transaction.xa.Xid xid,
                  int flags)
           throws javax.transaction.xa.XAException
        Specified by:
        start in interface javax.transaction.xa.XAResource
        Throws:
        javax.transaction.xa.XAException