XA Resource Manager Swiftlet

Overview

The XA Resource Manager Swiftlet manages distributed (XA) transactions within the SwiftMQ router, enabling support for two-phase commit (2PC) and recovery of transactional state. It tracks, coordinates, and recovers XA transactions, ensuring data consistency across multiple resources and providing mechanisms for handling heuristically completed transactions.

Features

XA Transaction Coordination and Two-Phase Commit

This Swiftlet implements the XA Resource Manager, providing full support for distributed transactions using the two-phase commit protocol. It tracks the lifecycle of XA transactions, including their preparation, commit, and rollback phases. The Swiftlet maintains an internal map of active and prepared transactions, allowing it to coordinate commit or rollback across all involved resources. During the prepare phase, each transaction is registered and its state is persisted, ensuring that the system can recover in the event of a failure. The Swiftlet also supports both one-phase and two-phase commit flows, enforcing protocol correctness by checking transaction state before allowing operations.

Transaction Timeout and Automatic Rollback

The Swiftlet enforces a configurable transaction timeout. If a transaction exceeds this timeout, it is automatically rolled back to prevent resource leaks and ensure system stability. This is managed by a timer that periodically checks all active transactions and invokes rollback on those that have timed out.

Prepared Transaction Recovery

On startup, the Swiftlet scans the persistent store for prepared transactions and reconstructs their state, ensuring that any in-doubt transactions from previous runs are properly recovered. This includes rebuilding prepared transactions from log records and registering them in the internal usage list for administrative visibility and manual intervention if necessary.

Configuration Example:

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

Heuristic Transaction Management

The Swiftlet tracks and manages heuristically completed transactions—those that were forcefully committed or rolled back outside the normal two-phase commit protocol. These are stored persistently in the sys$xa_heuristic queue and are visible in the usage list under heuristic-tx. The Swiftlet provides mechanisms to add, remove, and query heuristically completed transactions, supporting administrative actions such as forget to clean up heuristic state. Each heuristic record includes the Xid and the operation performed (COMMIT or ROLLBACK), ensuring transparency and auditability.

Persistent Heuristic Store

Heuristic outcomes are stored as persistent messages in the sys$xa_heuristic queue. On startup, the Swiftlet loads these records to reconstruct the heuristic state, ensuring that no heuristic completion is lost across restarts.

Manual Heuristic Management

Administrators can use management tools (such as the CLI or Explorer) to inspect, commit, rollback, or forget heuristically completed transactions. This is essential for resolving in-doubt transactions and maintaining consistency in distributed systems.

Configuration Example:

<swiftlet name="sys$xa"/>

Usage Lists for XA Transaction State

The Swiftlet maintains two usage lists: prepared-tx for prepared (in-doubt) XA transactions and heuristic-tx for heuristically completed transactions. These lists are exposed for management and monitoring, allowing administrators to view the current state of distributed transactions, perform manual recovery actions, and ensure that all transactional state is accounted for.

Prepared XA Transactions List

All XA transactions that have entered the prepared state are registered in the prepared-tx usage list. Each entry includes the Xid and is associated with management commands for commit and rollback.

Heuristically Completed Transactions List

Heuristically completed transactions are tracked in the heuristic-tx usage list, with each entry recording the Xid and the operation (COMMIT or ROLLBACK) performed.

Configuration Example:

<swiftlet name="sys$xa"/>

Internal Queue Naming

• sys$xa_heuristic — Persistent queue for storing heuristically completed XA transactions (COMMIT or ROLLBACK) for recovery and administrative management.

Configuration Guide

Changing the XA Transaction Scan Interval

Adjust the frequency at which the Swiftlet scans for prepared XA transactions to register them in the usage list. This can be useful in high-throughput environments where timely visibility of in-doubt transactions is important.

1. Edit the routerconfig.xml file.
2. Set the scan-interval attribute on the sys$xa swiftlet to the desired value in milliseconds.
3. Restart the router or reload the configuration.

<swiftlet name="sys$xa" scan-interval="10000"/>

Setting a Default XA Transaction Timeout

Configure the maximum allowed duration for XA transactions. Transactions exceeding this timeout will be automatically rolled back, preventing resource leaks and ensuring system responsiveness.

1. Edit the routerconfig.xml file.
2. Set the default-transaction-timeout attribute on the sys$xa swiftlet to the desired value in milliseconds.
3. Restart the router or reload the configuration.

<swiftlet name="sys$xa" default-transaction-timeout="120000"/>

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"/>