| = 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. |