JDBCXAResource (HSQLDB 2.4.0 API)
Date: 2017-04-09

org.hsqldb.jdbc.pool

## 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:
    `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

    Constructors
    Constructor and Description
    `JDBCXAResource(JDBCXADataSource xaDataSource, JDBCConnection connection)` Constructs a resource using the given data source and connection.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.