modules/tx-control/xaTransactions.mdtext

Title: Aries XA Transaction Control implementation
Notice:    Licensed to the Apache Software Foundation (ASF) under one
           or more contributor license agreements.  See the NOTICE file
           distributed with this work for additional information
           regarding copyright ownership.  The ASF licenses this file
           to you under the Apache License, Version 2.0 (the
           "License"); you may not use this file except in compliance
           with the License.  You may obtain a copy of the License at
           .
             http://www.apache.org/licenses/LICENSE-2.0
           .
           Unless required by applicable law or agreed to in writing,
           software distributed under the License is distributed on an
           "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
           KIND, either express or implied.  See the License for the
           specific language governing permissions and limitations
           under the License.

#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 [Quick Start Documentation][1]

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 <code>osgi.local.enabled</code> _and_ <code>osgi.xa.enabled</code>
properties set to <code>true</code>.

## 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 
<code>registerXAResource(XAResource)</code> method. 

Lifecycle callbacks can be registered against the current scope using the 
<code>preCompletion(Runnable)</code> and <code>postCompletion(Consumer<TransactionStatus>)</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 <code>registerLocalResource(LocalResource)</code> 
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 <code>XAResources</code>, 
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.





  [1]: quickstart.html#TODO