blob: 8e2e1d6c5d84eeae2b80484def0bc1c5c946888f [file] [log] [blame]
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 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.