XA Resource Manager Swiftlet

Overview

The XA Resource Manager Swiftlet (sys$xa) manages distributed (XA) transactions within the SwiftMQ router. It coordinates the two-phase commit protocol across multiple queues and resources, ensuring atomicity and consistency for transactions that span multiple systems. The Swiftlet handles transaction state, recovery, timeouts, and heuristic outcomes, integrating with the queue manager and persistent store.

Features

XA Transaction Coordination

The Swiftlet manages the lifecycle of distributed (XA) transactions, including starting, preparing, committing, and rolling back transactions that may span multiple queues. It implements the two-phase commit protocol, ensuring that all participating resources either commit or roll back changes atomically. The Swiftlet tracks transaction associations, enforces protocol rules (such as not allowing prepare on rollback-only transactions), and manages transaction state transitions. XA transactions are registered and tracked internally, with prepared transactions being periodically scanned and managed for recovery and administrative purposes.

Prepared Transaction Management

Prepared XA transactions are maintained in an internal usage list. The Swiftlet periodically scans and registers prepared transactions, making them visible for recovery or administrative intervention. Each prepared transaction is associated with its Xid and the queues involved, and can be committed or rolled back via administrative commands.

Transaction Timeout and Automatic Rollback

The Swiftlet enforces a configurable transaction timeout. If an XA transaction exceeds the allowed duration, it is automatically rolled back to prevent resource leaks and maintain consistency. The timeout mechanism is driven by a timer that periodically checks for expired transactions.

Configuration Example:

<swiftlet name="sys$xa" scan-interval="10000" default-transaction-timeout="60000"/>

Heuristic Transaction Handling

In cases where a distributed transaction cannot be completed normally (for example, due to failures or administrative intervention), the Swiftlet records heuristic outcomes. Heuristically completed transactions (either committed or rolled back outside the normal protocol) are tracked in a dedicated usage list and persisted in the internal queue sys$xa_heuristic. This ensures that administrators can review, forget, or resolve such transactions, maintaining transparency and auditability. The Swiftlet provides mechanisms to check for heuristic completions, determine the outcome (commit or rollback), and remove (forget) heuristic records when resolved.

Heuristic Queue Persistence

Heuristic transaction records are stored as persistent messages in the internal queue sys$xa_heuristic. This guarantees that heuristic outcomes survive router restarts and can be managed through the administrative interface.

Administrative Heuristic Management

Administrators can view, commit, rollback, or forget heuristic transactions using the management interface. The Swiftlet exposes commands to commit or rollback prepared transactions, which, upon completion, are recorded as heuristic outcomes if not related to routing transactions.

Configuration Example:

<swiftlet name="sys$xa">
  <usage>
    <heuristic-tx/>
  </usage>
</swiftlet>

XA Transaction Recovery

The Swiftlet supports automatic recovery of XA transactions after a router restart or failure. It rebuilds the list of prepared transactions by reading from the persistent store and reconstructs transaction state, ensuring that distributed transactions can be completed or resolved even after outages. The Swiftlet also recovers heuristic transaction records from the sys$xa_heuristic queue. This robust recovery mechanism is essential for high availability and distributed consistency.

Automatic Re-registration of Prepared Transactions

During startup, the Swiftlet scans the persistent store for prepared transactions and registers them in the usage list, making them available for administrative action or completion.

Configuration Example:

<swiftlet name="sys$xa">
  <usage>
    <prepared-tx/>
  </usage>
</swiftlet>

Internal Queue Naming

• sys$xa_heuristic — Internal persistent queue for storing records of heuristically completed XA transactions (commit or rollback).

Configuration Guide

Configuring Transaction Timeout and Scan Interval

To ensure that XA transactions do not run indefinitely and that prepared transactions are promptly registered for recovery, you may want to adjust the transaction timeout and scan interval. This is useful in environments with strict transactional guarantees or where rapid recovery is required.

1. Set the default-transaction-timeout attribute to specify the maximum allowed duration (in milliseconds) for an XA transaction.
2. Set the scan-interval attribute to control how often the Swiftlet scans for prepared transactions to register them in the usage list.

<swiftlet name="sys$xa" scan-interval="10000" default-transaction-timeout="60000"/>

CLI Commands

commit

Description: Commit

Usage: commit <id>

rollback

Description: Rollback

Usage: rollback <id>

Configuration Reference

The top-level entity in routerconfig.xml is <swiftlet name="sys$xa">.

<swiftlet name="sys$xa"> Properties

These properties are attributes of the <swiftlet name="sys$xa"> entity.

Parameter	Type	Default	Mandatory	Reboot Required	Description
scan-interval	Long	20000	No	No	Interval to scan prepared XA transaction to put into the Usage List (min: 500)
default-transaction-timeout	Long	0	No	No	Max. time a XA transaction can run, thereafter it will be rolled back (min: 0)

<swiftlet name="sys$xa" scan-interval="20000" default-transaction-timeout="0"/>