XA Resource Manager Swiftlet

The XA Resource Manager Swiftlet is the central XA resource to a router. Only because of simplification reasons it is a component of the standard distribution (it does not consume any resources). 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 to abort these transactions manually via the SwiftMQ Explorer or via CLI.

Settings

The Swiftlet has 2 attributes to configure, a scan 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 ansychronously. The scan interval value determines in which intervals the Swiftlet checks for pending XA transactions which 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 indoubt XA transactions here for manual commit/rollback.

Default Transaction Timeout

A transaction timeout is the 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

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, press the right mouse button and you may now choose between commit/rollback:

The entity table of the usage folder may also be displayed and you may select the respective line and activate the commit/rollback by the respective buttons:

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 transctions until the driving transaction manager commands to forget it. Therefore, when an XA transaction has been heuristical completed with SwiftMQ Explorer or CLI, it is still stored under folder Usage / Heuristically completed XA Transactions until the recovery is started by a transaction manager:

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

Configuration

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

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

of the router's configuration file. One can use the SwiftMQ Exlorer or CLI for configuration as well. They both save into that file.

Attributes of Element "swiftlet"

Definition

Attribute Type Mandatory Description
scan-interval java.lang.Long No Interval to scan prepared XA transaction to put into the Usage List
default-transaction-timeout java.lang.Long No Max. time a XA transaction can run, thereafter it will be rolled back

Values

Attribute Values
scan-interval Min: 500
Default: 120000
default-transaction-timeout Min: 0
Default: 0

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

Attribute Type Mandatory Description
name java.lang.String Yes Name of this Prepared XA Transaction
xid java.lang.String No Xid (Internal Representation)

Values

Attribute Values
xid

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

Attribute Type Mandatory Description
name java.lang.String Yes Name of this Heuristically completed XA Transaction
xid java.lang.String No Xid (Internal Representation)
operation java.lang.String No Operation

Values

Attribute Values
xid
operation Choice: COMMIT ROLLBACK
← Trace SwiftletNext →