LocalXAConnectionFactory.LocalXAResource (Apache Tomcat 10.1.5 API Documentation)

Package org.apache.tomcat.dbcp.dbcp2.managed

## Class LocalXAConnectionFactory.LocalXAResource

- java.lang.Object
- - org.apache.tomcat.dbcp.dbcp2.managed.LocalXAConnectionFactory.LocalXAResource

- All Implemented Interfaces:
    `XAResource`
  Enclosing class:
    LocalXAConnectionFactory

      protected static class LocalXAConnectionFactory.LocalXAResource
      extends Object
      implements XAResource

  LocalXAResource is a fake XAResource for non-XA connections. When a transaction is started the connection auto-commit is turned off. When the connection is committed or rolled back, the commit or rollback method is called on the connection and then the original auto-commit value is restored.

  The LocalXAResource also respects the connection read-only setting. If the connection is read-only the commit method will not be called, and the prepare method returns the XA_RDONLY.

  It is assumed that the wrapper around a managed connection disables the setAutoCommit(), commit(), rollback() and setReadOnly() methods while a transaction is in progress.

  Since:
    2.0

- - ### 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 | Description
    --- | ---
    `LocalXAResource​(Connection localTransaction)` | Construct a new instance for a given connection.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `commit​(Xid xid, boolean flag)` | Commits the transaction and restores the original auto commit setting.
    `void` | `end​(Xid xid, int flag)` | This method does nothing.
    `void` | `forget​(Xid xid)` | Clears the currently associated transaction if it is the specified xid.
    `int` | `getTransactionTimeout()` | Always returns 0 since we have no way to set a transaction timeout on a JDBC connection.
    `Xid` | `getXid()` | Gets the current xid of the transaction branch associated with this XAResource.
    `boolean` | `isSameRM​(XAResource xaResource)` | Returns true if the specified XAResource == this XAResource.
    `int` | `prepare​(Xid xid)` | This method does nothing since the LocalXAConnection does not support two-phase-commit.
    `Xid[]` | `recover​(int flag)` | Always returns a zero length Xid array.
    `void` | `rollback​(Xid xid)` | Rolls back the transaction and restores the original auto commit setting.
    `boolean` | `setTransactionTimeout​(int transactionTimeout)` | Always returns false since we have no way to set a transaction timeout on a JDBC connection.
    `void` | `start​(Xid xid, int flag)` | Signals that a the connection has been enrolled in a transaction.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### LocalXAResource

          public LocalXAResource​(Connection localTransaction)

      Construct a new instance for a given connection.
      Parameters:
        `localTransaction` - A connection.

  - ### Method Detail

    - #### commit

          public void commit​(Xid xid,
                             boolean flag)
                      throws XAException

      Commits the transaction and restores the original auto commit setting.
      Specified by:
        `commit` in interface `XAResource`
      Parameters:
        `xid` - the id of the transaction branch for this connection
        `flag` - ignored
      Throws:
        `XAException` - if connection.commit() throws an SQLException

    - #### end

          public void end​(Xid xid,
                          int flag)
                   throws XAException

      This method does nothing.
      Specified by:
        `end` in interface `XAResource`
      Parameters:
        `xid` - the id of the transaction branch for this connection
        `flag` - ignored
      Throws:
        `XAException` - if the connection is already enlisted in another transaction

    - #### forget

          public void forget​(Xid xid)

      Clears the currently associated transaction if it is the specified xid.
      Specified by:
        `forget` in interface `XAResource`
      Parameters:
        `xid` - the id of the transaction to forget

    - #### getTransactionTimeout

          public int getTransactionTimeout()

      Always returns 0 since we have no way to set a transaction timeout on a JDBC connection.
      Specified by:
        `getTransactionTimeout` in interface `XAResource`
      Returns:
        always 0

    - #### getXid

          public Xid getXid()

      Gets the current xid of the transaction branch associated with this XAResource.
      Returns:
        the current xid of the transaction branch associated with this XAResource.

    - #### isSameRM

          public boolean isSameRM​(XAResource xaResource)

      Returns true if the specified XAResource == this XAResource.
      Specified by:
        `isSameRM` in interface `XAResource`
      Parameters:
        `xaResource` - the XAResource to test
      Returns:
        true if the specified XAResource == this XAResource; false otherwise

    - #### prepare

          public int prepare​(Xid xid)

      This method does nothing since the LocalXAConnection does not support two-phase-commit. This method will return XAResource.XA_RDONLY if the connection isReadOnly(). This assumes that the physical connection is wrapped with a proxy that prevents an application from changing the read-only flag while enrolled in a transaction.
      Specified by:
        `prepare` in interface `XAResource`
      Parameters:
        `xid` - the id of the transaction branch for this connection
      Returns:
        XAResource.XA_RDONLY if the connection.isReadOnly(); XAResource.XA_OK otherwise

    - #### recover

          public Xid[] recover​(int flag)

      Always returns a zero length Xid array. The LocalXAConnectionFactory can not support recovery, so no xids will ever be found.
      Specified by:
        `recover` in interface `XAResource`
      Parameters:
        `flag` - ignored since recovery is not supported
      Returns:
        always a zero length Xid array.

    - #### rollback

          public void rollback​(Xid xid)
                        throws XAException

      Rolls back the transaction and restores the original auto commit setting.
      Specified by:
        `rollback` in interface `XAResource`
      Parameters:
        `xid` - the id of the transaction branch for this connection
      Throws:
        `XAException` - if connection.rollback() throws an SQLException

    - #### setTransactionTimeout

          public boolean setTransactionTimeout​(int transactionTimeout)

      Always returns false since we have no way to set a transaction timeout on a JDBC connection.
      Specified by:
        `setTransactionTimeout` in interface `XAResource`
      Parameters:
        `transactionTimeout` - ignored since we have no way to set a transaction timeout on a JDBC connection
      Returns:
        always false

    - #### start

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

      Signals that a the connection has been enrolled in a transaction. This method saves off the current auto commit flag, and then disables auto commit. The original auto commit setting is restored when the transaction completes.
      Specified by:
        `start` in interface `XAResource`
      Parameters:
        `xid` - the id of the transaction branch for this connection
        `flag` - either XAResource.TMNOFLAGS or XAResource.TMRESUME
      Throws:
        `XAException` - if the connection is already enlisted in another transaction, or if auto-commit could not be disabled