XATransactionalResource (Transactions JTA 4.0.6 API)
Date: 2018-01-11

com.atomikos.datasource.xa

## Class XATransactionalResource

- java.lang.Object
- - com.atomikos.datasource.xa.XATransactionalResource

- All Implemented Interfaces:
    RecoverableResource, TransactionalResource
  Direct Known Subclasses:
    AcceptAllXATransactionalResource, JdbcTransactionalResource, JmsTransactionalResource, TemporaryXATransactionalResource

      public abstract class XATransactionalResource
      extends java.lang.Object
      implements TransactionalResource

  An abstract XA implementation of a transactional resource. For a particular XA data source, it is necessary to implement the refreshXAConnection method, because in general there is no standard way of getting XAResource instances. Therefore, this class is agnostic about it. It is assumed that there is at most one instance per (root transaction, server) combination. Otherwise, siblings can not be mapped to the same ResourceTransaction! This instance is responsible for mapping siblings to ResourceTransaction instances.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected javax.transaction.xa.XAResource` | `xares_`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XATransactionalResource(java.lang.String servername)` Construct a new instance with a default XidFactory.
    `XATransactionalResource(java.lang.String servername, XidFactory factory)` Construct a new instance with a custom XidFactory.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `acceptsAllXAResources()`
    `void` | `close()` The default close operation.
    `protected XID` | `createXid(java.lang.String tid)` Create an XID for the given tx.
    `java.lang.String` | `getName()`
    `ResourceTransaction` | `getResourceTransaction(CompositeTransaction ct)`
    `javax.transaction.xa.XAResource` | `getXAResource()` Get the XAResource instance that this instance is using.
    `XidFactory` | `getXidFactory()` Get the xidFactory for this instance.
    `boolean` | `isClosed()` Test if the resource is closed.
    `boolean` | `isSameRM(RecoverableResource res)`
    `protected boolean` | `needsRefresh()` Check if the XAResource needs to be refreshed.
    `void` | `recover()`
    `protected abstract javax.transaction.xa.XAResource` | `refreshXAConnection()` Utility method to establish and refresh the XAResource.
    `void` | `setAcceptAllXAResources(boolean val)` Specify whether to entirely shortcut the isSameRM method of the XAResource implementations, and always return true for usesXAResource.
    `void` | `setRecoveryService(RecoveryService recoveryService)`
    `void` | `setXidFactory(XidFactory factory)` Set the XID factory, needed for online management tools.
    `boolean` | `usesWeakCompare()` Test if this instance uses weak compare mode.
    `boolean` | `usesXAResource(javax.transaction.xa.XAResource xares)` Test if the XAResource is used by this instance.
    `void` | `useWeakCompare(boolean weakCompare)` Set this instance to use the weak compare mode setting.

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

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

- - ### Field Detail

    - #### xares_

          protected javax.transaction.xa.XAResource xares_

  - ### Constructor Detail

    - #### XATransactionalResource

          public XATransactionalResource(java.lang.String servername)

      Construct a new instance with a default XidFactory.
      Parameters:
        `servername` - The servername, needed to identify the xid instances for the current configuration. Max BYTE length is 64!

    - #### XATransactionalResource

          public XATransactionalResource(java.lang.String servername,
                                 XidFactory factory)

      Construct a new instance with a custom XidFactory.
      Parameters:
        `servername` - The servername, needed to identify the xid instances for the current configuration. Max BYTE length is 64!
        `factory` - The custom XidFactory.

  - ### Method Detail

    - #### refreshXAConnection

          protected abstract javax.transaction.xa.XAResource refreshXAConnection()
                                                                          throws ResourceException

      Utility method to establish and refresh the XAResource. An XAResource is actually a connection to a back-end resource, and this connection needs to stay open for the transactional resource instance. The resource uses the XAResource regularly, but sometimes the back-end server can close the connection after a time-out. At intialization time and also after such a time-out, this method is called to refresh the XAResource instance. This is typically done by (re-)establishing a connection to the server and keeping this connection open!.
      Returns:
        XAResource A XAResource instance that will be used to represent the server.
      Throws:
        `ResourceException` - On failure.

    - #### getXidFactory

          public XidFactory getXidFactory()

      Get the xidFactory for this instance. Needed by XAResourceTransaction to create new XID.
      Returns:
        XidFactory The XidFactory for the resource.

    - #### needsRefresh

          protected boolean needsRefresh()

      Check if the XAResource needs to be refreshed.
      Returns:
        boolean True if the XAResource needs refresh.

    - #### useWeakCompare

          public void useWeakCompare(boolean weakCompare)

      Set this instance to use the weak compare mode setting. This method should be called before recovery is done, so before initialization of the transaction service. this is no longer needed at all, and taken care of by the transaction service automatically.
      Throws:
        `java.lang.IllegalStateException` - If recovery was already done, meaning that the transaction service is already running.

    - #### usesWeakCompare

          public boolean usesWeakCompare()

      Test if this instance uses weak compare mode.
      Returns:
        boolean True iff weak compare mode is in use. This mode is relevant for integration with certain vendors whose XAResource instances do not correctly implement isSameRM.

    - #### setAcceptAllXAResources

          public void setAcceptAllXAResources(boolean val)

      Specify whether to entirely shortcut the isSameRM method of the XAResource implementations, and always return true for usesXAResource. The consequence is that branches are always different (even in the same tx) and that the resource names will not entirely match in the logfiles. Besides that, no serious problems should happen.
      Parameters:
        `val` -

    - #### acceptsAllXAResources

          public boolean acceptsAllXAResources()

      Returns:
        boolean True if usesXAResource is always true.

    - #### usesXAResource

          public boolean usesXAResource(javax.transaction.xa.XAResource xares)

      Test if the XAResource is used by this instance.
      Parameters:
        `xares` - The XAResource to test.
      Returns:
        boolean True iff this instance uses the same back-end resource, in as far as this can be determined by this instance.

    - #### getXAResource

          public javax.transaction.xa.XAResource getXAResource()

      Get the XAResource instance that this instance is using.
      Returns:
        XAResource The XAResource instance.

    - #### getResourceTransaction

          public ResourceTransaction getResourceTransaction(CompositeTransaction ct)
                                                     throws ResourceException,
                                                            java.lang.IllegalStateException

      Specified by:
        `getResourceTransaction` in interface `TransactionalResource`
      Throws:
        `ResourceException`
        `java.lang.IllegalStateException`
      See Also:
        `TransactionalResource`

    - #### getName

          public java.lang.String getName()

      Specified by:
        `getName` in interface `RecoverableResource`
      See Also:
        `TransactionalResource`

    - #### close

          public void close()
                     throws ResourceException

      The default close operation. Subclasses may need to override this method in order to process XA-specific close procedures such as closing connections.
      Specified by:
        `close` in interface `RecoverableResource`
      Throws:
        `ResourceException`

    - #### isClosed

          public boolean isClosed()
                           throws ResourceException

      Test if the resource is closed.
      Specified by:
        `isClosed` in interface `RecoverableResource`
      Returns:
        boolean True if closed.
      Throws:
        `ResourceException`

    - #### isSameRM

          public boolean isSameRM(RecoverableResource res)
                           throws ResourceException

      Specified by:
        `isSameRM` in interface `RecoverableResource`
      Throws:
        `ResourceException`
      See Also:
        `RecoverableResource`

    - #### setRecoveryService

          public void setRecoveryService(RecoveryService recoveryService)
                                  throws ResourceException

      Specified by:
        `setRecoveryService` in interface `RecoverableResource`
      Throws:
        `ResourceException`
      See Also:
        `RecoverableResource`

    - #### setXidFactory

          public void setXidFactory(XidFactory factory)

      Set the XID factory, needed for online management tools.
      Parameters:
        `factory` -

    - #### createXid

          protected XID createXid(java.lang.String tid)

      Create an XID for the given tx.
      Parameters:
        `tid` - The tx id.
      Returns:
        Xid A globally unique Xid that can be recovered by any resource that connects to the same EIS.

    - #### recover

          public void recover()

      Specified by:
        `recover` in interface `RecoverableResource`

Copyright © 2018. All Rights Reserved.