= Aries XA Transaction Control implementation

The Aries XA Transaction control implementation is available at the following maven coordinates:

     <dependency>
         <groupId>org.apache.aries.tx-control</groupId>
         <artifactId>tx-control-service-xa</artifactId>
         <version>${aries.tx.control.version}</version>
     </dependency>

It is based on the JTA transaction manager provided by Apache Geronimo.

== Using the Transaction Control Service

For the basics of using the Transaction Control Service see the link:quickstart.html#TODO[Quick Start Documentation]

As per the Transaction Control specification the Aries XA implementation registers a  TransactionControl service in the OSGi Service Registry.

The Aries XA Transaction Control implementation is able to support the use of both XA  and Local Resources within the same transaction.
The service is therefore registered  with the `osgi.local.enabled` _and_ `osgi.xa.enabled` properties set to `true`.

== XA Transactions

The XA transactions created by the XA Transaction Control implementation are not configured to create a transaction log.
Therefore the XA Transactions are _not recoverable_ in the event of failure.
This may change in the future if transaction log support is added to the implementation.

The primary difference between XA and Local Transactions is that XA transactions _are_ atomic across multiple resources.
In particular, if two  resources.
This means that all resources in the transaction will be committed or rolled back together.

XA transactions are therefore best suited to scenarios where multiple resources are accessed within the transaction, particularly if consistency between the resources is important.

== Working with XA transactions

The XA Transaction Control Service supports participants in ongoing transactions via the  `registerXAResource(XAResource)` method.

Lifecycle callbacks can be registered against the current scope using the  `preCompletion(Runnable)` and `postCompletion(Consumer)</code> methods.`

== Local Resources and the Last Participant Gambit

In addition to supporting XA resources the XA Aries Transaction Control implementation also supports  Local Resources which can be added using the `registerLocalResource(LocalResource)`  method.

When local resources are added to the XA transaction they are processed in a special way.
When the two-phase commit is preparing resources it first prepares all of the registered `XAResources`,  then the Local resources are committed or rolled back as appropriate, then the XAResources are completed.
This is known as the _Last Resource Gambit_.

The value of the Last Resource Gambit is highest when there is exactly one Local resource in the transaction.
In this case the Local resource is effectively doing a prepare and commit/rollback in one step, but as all of the other resources have been prepared already there is _almost_ no risk of inconsistency across the resources.
As the number of Local Resources involved in the transaction rises the risk of inconsistency becomes much greater.
It is therefore recommended that XA transactions contain _zero_ or _one_ Local resources, although any number may be registered.