11.3.2. About the LRCO Optimization for Single-phase Commit (1PC)

Although the 2-phase commit protocol (2PC) is more commonly encountered with transactions, some situations do not require, or cannot accommodate, both phases. In these cases, you can use the single phase commit (1PC) protocol. One situation where this might happen is when a non-XA-aware datasource needs to participate in the transaction.
In these situations, an optimization known as the Last Resource Commit Optimization (LRCO) is employed. The single-phase resource is processed last in the prepare phase of the transaction, and an attempt is made to commit it. If the commit succeeds, the transaction log is written and the remaining resources go through the 2PC. If the last resource fails to commit, the transaction is rolled back.
While this protocol allows for most transactions to complete normally, certain types of error can cause an inconsistent transaction outcome. Therefore, use this approach only as a last resort.
Where a single local TX datasource is used in a transaction, the LRCO is automatically applied to it.

11.3.2.1. Commit Markable Resource

Summary

Configuring access to a resource manager via the Commit Markable Resource (CMR) interface ensures that a 1PC resource manager can be reliably enlisted in a 2PC transaction. It is an implementation of the LRCO algorithm, which makes non-XA resource fully recoverable.

Previously, adding 1PC resources to a 2PC transaction was achieved via the LRCO method, however there is a window of failure in LRCO. Following the procedure below for adding 1PC resources to a 2PC transaction via the LRCO method:
  1. Prepare 2PC
  2. Commit LRCO
  3. Write tx log
  4. Commit 2PC
If the procedure crashes between steps 2 and step 3, you cannot commit the 2PC. CMR eliminates this restriction and allows 1PC to be reliably enlisted in a 2PC transaction.
Restrictions

A transaction may contain only one CMR resource.

Prerequisites

You must have a table created for which the following SQL would work:

SELECT xid,actionuid FROM _tableName_ WHERE transactionManagerID IN (String[])
DELETE FROM _tableName_ WHERE xid IN (byte[[]])
INSERT INTO _tableName_ (xid, transactionManagerID, actionuid) VALUES (byte[],String,byte[])

Example 11.1. Some examples of the SQL query

Sybase:
CREATE TABLE xids (xid varbinary(144), transactionManagerID varchar(64), actionuid varbinary(28))
Oracle:
CREATE TABLE xids (xid RAW(144), transactionManagerID varchar(64), actionuid RAW(28))
CREATE UNIQUE INDEX index_xid ON xids (xid)
IBM:
CREATE TABLE xids (xid VARCHAR(255) for bit data not null, transactionManagerID
varchar(64), actionuid VARCHAR(255) for bit data not null)
CREATE UNIQUE INDEX index_xid ON xids (xid)
SQL Server:
CREATE TABLE xids (xid varbinary(144), transactionManagerID varchar(64), actionuid varbinary(28))
CREATE UNIQUE INDEX index_xid ON xids (xid)
Postgres:
CREATE TABLE xids (xid bytea, transactionManagerID varchar(64), actionuid bytea)
CREATE UNIQUE INDEX index_xid ON xids (xid)
Enabling a resource manager as CMR

By default, the CMR feature is disabled for datasources. To enable it, you must create or modify the datasource configuration and ensure that the connectible attribute is set to true. An example configuration entry in the datasources section of a server xml configuration file could be as follows:

<datasource enabled="true" jndi-name="java:jboss/datasources/ConnectableDS" pool-name="ConnectableDS" jta="true" use-java-context="true" spy="false" use-ccm="true" connectable="true"/>

Note

This feature is not applicable to XA datasources.
You can also enable a resource manager as CMR using CLI as follows:
/subsystem=datasources/data-source=ConnectableDS:add(enabled="true", jndi-name="java:jboss/datasources/ConnectableDS", jta="true", use-java-context="true", spy="false", use-ccm="true", connectable="true", connection-url="validConnectionURL", driver-name="h2")
Updating an existing resource to use the new CMR feature

If you only need to update an existing resource to use the new CMR feature, then simply modifiy the connectable attribute:

/subsystem=datasources/data-source=ConnectableDS:write-attribute(name=connectable,value=true)

Identifying CMR capable datasources

The transaction subsystem identifies the datasources that are CMR capable through an entry to the transaction subsystem config section as shown below:

<subsystem xmlns="urn:jboss:domain:transactions:3.0">
    ...
    <commit-markable-resources>
        <commit-markable-resource jndi-name="java:jboss/datasources/ConnectableDS">
            <xid-location name="xids" batch-size="100" immediate-cleanup="false"/>
        </commit-markable-resource>
        ...
    </commit-markable-resources>
</subsystem>

Note

You must restart the server after adding the CMR.