XA Resource Manager Swiftlet

The XA Resource Manager Swiftlet is the central XA resource to a router. Together with the JMS XA/ASF Swiftlet and the Routing Swiftlet, it is responsible for the administration of so-called in-doubt transactions. These are unfinished prepared XA transactions.

On startup, the XA Resource Manager Swiftlet checks if prepared XA transactions are stored within the Store Swiftlet. In this case, it reconstructs these transactions incl. all locks. A warning message is displayed during the startup with the hint to commit or abort these transactions manually.

Settings

The Swiftlet has 2 attributes to configure, a scanning interval and a transaction timeout.

Scan Interval

The Prepared XA Transactions node of the Swiftlet contains transactions in a prepared state. The update of this node consumes time and resources and is therefore made asynchronously. The scan interval value determines in which intervals the Swiftlet checks for pending XA transactions that are in a prepared state and enlists these below the Prepared XA Transactions node. The default value is 120000 ms (2 minutes) which is quite enough to enlist in-doubt XA transactions here for manual commit/rollback.

Default Transaction Timeout

A transaction timeout is a time after which a running and not yet prepared XA transaction is aborted (rolled back). The sense is to avoid long-running transactions and lock exhaustions. The value of this attribute is the default value. A transaction manager of an application server is able to get and set this value via the resp. methods of SwiftMQ's XAResource. The default value is 0 which means no timeout.

Heuristic Completion

Heuristic Branch Completion

According to the XA specification, a resource manager that has prepared to commit a transaction branch may decide to commit or roll back its work independently of the transaction manager. It could then unlock shared resources. This may leave them in an inconsistent state across the distributed transaction. This chapter explains how to perform heuristic commits and rollbacks of SwiftMQ XA transaction branches.

Heuristic Commit/Rollback via SwiftMQ Explorer App

The list of in-doubt transactions is located within the "Usage / Prepared XA Transactions" folder of the XA Resource Manager Swiftlet:

You have to select the respective transaction, and may now choose between commit/rollback.

Heuristic Commit/Rollback via CLI

Example:

    Welcome to SwiftMQ!

    Username:
    Password:
    Trying to connect ... connected
    Type 'help' to get a list of available commands.
    > Router 'router1' is available for administration.

    > sr r
    router1> cc sys$xa
    router1/sys$xa> cc usage/prepared-tx
    router1/sys$xa/usage/prepared-tx> lc

    Entity List: Prepared XA Transactions
    Description: Prepared XA Transactions

    Entities in this List:
    ----------------------
    1
    2
    3
    4

    router1/sys$xa/usage/prepared-tx> rollback 3
    router1/sys$xa/usage/prepared-tx> commit 4
    router1/sys$xa/usage/prepared-tx> lc

    Entity List: Prepared XA Transactions
    Description: Prepared XA Transactions

    Entities in this List:
    ----------------------
    1
    2

    router1/sys$xa/usage/prepared-tx>

Heuristically completed XA Transactions

According to the XA specification, an XA resource has to store information about heuristically completed XA transactions until the driving transaction manager commands to forget it. Therefore, when an XA transaction has been heuristically completed with SwiftMQ Explorer App or CLI, it is still stored under the folder Usage / Heuristically completed XA Transactions until the recovery is started by a transaction manager:

If automatic recovery is not done by a transaction manager for any reason, the entries can be manually deleted.

How to handle XA Client Disconnects

When a XA client disconnects for whatever reason and it has incomplete XA transaction, we need to differ 2 cases:

1. XA transaction has reached prepared state.

2. XA transaction has not reached prepared state.

Case 1 is handled above in the previous section to complete the transaction heuristically.

Case 2 is where the transaction timeout jumps in.

Per default, this timeout is 0 (no timeout). You should leave it at the default because setting a timeout may end long-running transaction, i.e. having a consumer on a queue waiting for messages. This consume must be inside a transaction so this is a long-running one.

Consuming messages inside a transaction locks messages delivered to the client’s cache. If no transaction timeout is set, these messages remain locked forever. To unlock them in case the client has disconnected, set the timeout to a low value, i.e. 1000 ms and wait until the transaction is rolled back.

You can see that in the warning.log:

2024-08-21 14:38:27.369/sys$xa/WARNING/[XALiveContextImpl, xid=[XidImpl, branchQualifier=2, formatId=0, globalTransactionId=1724243855595, routing=false], prepared=false]transaction timeout, transaction rolled back!

Thereafter reset the transaction timeout to 0.

Configuration

The configuration of the XA Resource Manager Swiftlet is defined within the element

      <swiftlet name="sys$xa" .../>

of the router's configuration file.

Attributes of Element "swiftlet"

Definition

Values

Element "usage", Parent Element: "swiftlet"

Usage.

Element List "prepared-tx", Parent Element: "usage"

Prepared XA Transactions. This element list contains zero or more "prepared-xa-transaction" elements with this template definition:

Definition

Values

Element List "heuristic-tx", Parent Element: "usage"

Heuristically completed XA Transactions. This element list contains zero or more "heuristic-xa-transaction" elements with this template definition:

Definition

Values