Deep Dive into ShardingSphere XA Distributed Transaction Support and Atomikos Integration

Overview of ShardingSphere XA Support

ShardingSphere is an open‑source distributed database middleware that offers data sharding, distributed transactions, and governance through three independent products—JDBC, Proxy, and the planned Sidecar—each of which can be mixed and deployed together.

CAP Theory and Distributed Transactions

The CAP theorem explains the trade‑offs among Consistency (all nodes see the same data at the same time), Availability (every request receives a response within a bounded time), and Partition Tolerance (the system continues operating despite network partitions).

X/Open DTP Model and XA Specification

The X/Open DTP model defines three roles: Application Program (AP) that starts and ends a transaction, Resource Manager (RM) such as a database, and Transaction Manager (TM) that coordinates the transaction. The XA interface includes the functions xa_start, xa_end, xa_prepare, xa_commit, and xa_rollback.

MySQL XA Support

MySQL has supported XA transactions since version 5.0.3, but only the InnoDB storage engine implements them. The XA SQL syntax includes commands like XA START xid, XA END xid, XA PREPARE xid, XA COMMIT xid, and XA ROLLBACK xid.

JTA and Java Integration

JTA (Java Transaction API) maps the XA specification to Java interfaces: javax.transaction.TransactionManager, javax.transaction.UserTransaction, javax.transaction.xa.XAResource, and javax.transaction.xa.Xid, enabling Java applications to participate in XA transactions.

ShardingSphere Integration with Atomikos

ShardingSphere uses an SPI mechanism to load

org.apache.shardingsphere.transaction.xa.atomikos.manager.AtomikosTransactionManager

. During initialization it creates an XADataSource for each data source, registers the resource with Atomikos, and prepares the ShardingTransactionManager implementation.

Transaction Lifecycle in Atomikos

Begin : com.atomikos.icatch.imp.CompositeTransactionImp.begin() creates a composite transaction, registers the XA resource, and calls XAResource.start(xid, TMNOFLAGS) (or TMJOIN for reused connections).

Get Connection :

org.apache.shardingsphere.transaction.xa.jta.datasource.XATransactionDataSource.getConnection()

obtains a JDBC connection, wraps it as an XAConnection, enlists the XAResource with the current JTA transaction, and registers a Synchronization to clean up after completion.

Commit : The coordinator checks the number of participants. If there is only one, it performs a one‑phase commit; otherwise it executes the two‑phase commit: XAResource.prepare(xid) followed by XAResource.commit(xid, false) for each participant.

Rollback : The transaction is suspended (which issues XAResource.end(xid, TMSUCCESS)) and then XAResource.rollback(xid) is called for each participant.

Recovery Mechanism

Atomikos records transaction states in a log (in‑memory cache plus a file‑system backup). A recovery timer initialized in com.atomikos.icatch.imp.TransactionServiceImp.init() periodically invokes com.atomikos.datasource.xa.XATransactionalResource.recover(). Recovery proceeds by:

Calling XAResource.recover() to obtain all prepared XIDs from the resource (e.g., MySQL’s XA RECOVER statement).

Fetching expired committing XIDs from the log ( RecoveryLogImp.getCommittingParticipants()).

Matching the two sets: if an XID appears in the log, XAResource.commit is replayed; otherwise XAResource.rollback (presumed abort) is executed.

Key Code Snippets

XAResource.start(xid, XAResource.TMNOFLAGS);

XAResource.prepare(xid);

XAResource.commit(xid, false);

XAResource.rollback(xid);

Illustrative Diagrams