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 [Aries XA Transaction Control service][1] 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.

  [1]: xaTransactions.html