Title: Using the Last Resource Gambit 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.

#Using the Last Resource Gambit

The Last Resource Gambit is a technique by which a non-XA capable resource may be (relatively) safely included in a two-phase commit transaction containing multiple resources.

Importantly:

* The transaction must be 2-phase (typically XA)
* All but one of the resources must be XA capable
* The Transaction Manager must support the Last Resource Gambit

##How does it work?

In a two phase commit/rollback the Transaction Manager prepares all of the resources before calling commit.
This means that the resources have the opportunity to do any constraint checking and buffer flushing before committing, so that they know that a commit will succeed.
If any of the prepare calls fail then all of the resources (including the ones that were already prepared) may be rolled back to ensure consistency.

If a "local" (i.e.
one phase) resource is included in the transaction then this model breaks.
It is not possible to prepare a one-phase resource, so typically a transaction manager must "commit and hope" expecting that all other resources will commit successfully.

In the case of the Last Resource Gambit this possiblity can be reduced to near zero by including the local resource as the "last resource".
Specifically all of the XA resources are prepared, and if the prepare succeeds then the local resource is committed.
If the commit succeeds then all of the XA resources are committed, otherwise the XA resources are rolled back.
This model means that the overall transaction is robust to  resource failures.

##Taking advantage of the Last Resource Gambit

The link:xaTransactions.html[Aries XA Transaction Control service] implements the last resource gambit automatically, so there is nothing that needs to be explicitly done by the client to enable the behaviour, other than to use a local resource alongside XA resources.

For example, if one database in use is HSQLDB, which does not support XA, but two others use H2,  which does support XA, then the following configurations would be used:

_org.apache.aries.tx.control.jdbc.xa_

 osgi.jdbc.driver.class=org.h2.Driver
 url=jdbc:h2:tcp://192.168.1.31:12345/path/to/db

_org.apache.aries.tx.control.jdbc.xa_

 osgi.jdbc.driver.class=org.h2.Driver
 url=jdbc:h2:tcp://192.168.1.63:23456/path/to/another/db

_org.apache.aries.tx.control.jpa.local_

 osgi.jdbc.driver.class=org.hsqldb.jdbc.JDBCDriver
 url=jdbc:hsqldb:hsql://192.168.1.127/xdb"
 osgi.unit.name=jpa-workspace

If these three resource providers are used in the same transaction then the Last Resource Gambit will ensure that the one-phase resource is committed reliably.