CMR is neat Narayana feature enabling full XA transaction capability for one non-XA JDBC resource.
This gives you a way to engage a database resource to XA transaction even
the JDBC driver is not fully XA capable (or you just have a design restriction on it)
while transaction data consistency is kept.
Last resource commit optimization (aka. LRCO)
Maybe you will say "adding one non-XA resource to a transaction is well-known LRCO optimization".
And you are right. But just partially. The last resource commit optimization (abbreviated as LRCO)
provides a way to enlist and process one non-XA datasource to the global transaction managed by the transaction manager. But LRCO contains a pitfall. When the crash of the system
(or the connection) happens in particular point of the time,
during two-phase commit processing,
it causes data inconsistency. Namely, the LRCO could be committed while the rest of the resources will be rolled-back.
Let's elaborate a bit on the LRCO failure. Let's say we have a JMS resource where we send a message to a message broker and non-XA JDBC datasource where we save information to the database.
NOTE: The example refers to the Narayana two-phase commit implemenation.
- updating the database with
INSERT INTO SQL command, enlisting LRCO resource under the transaction
- sending a message to the JMS broker, enlisting the JMS resource to the transaction
- Narayana starts the two phase commit processing
prepare is called to JMS XA resource, the transaction log is stored
at the JMS broker sideprepare phase for the LRCO means to call commit at the non-XA
datasource. That call makes the data changes visible to the outer world.- crash of the Narayana JVM occurs before the Narayana can preserve
information of commit to its transaction log store
- after the Narayana restarts there is no notion about the existence of any
transaction thus the prepared JMS resource is rolled-back during transaction recovery
Note: roll-backing of the JMS resource is caused by presumed abort strategy
applied in the Narayana. If transaction manager does do not apply the presumed abort then
you end ideally not better than in the transaction heuristic state.
The LRCO processing is about ordering the LRCO resource as the last
during the transaction manager 2PC
prepare phase.
At place where transaction normally calls prepare at XAResources there is called
commit at the LRCO's underlaying non-XA resource.
Then during the transaction manager commit phase there is called nothing for the LRCO.
Commit markable resource (aka. CMR)
The Commit Markable Resource, abbreviated as CMR, is an enhancement of the last resource commit optimization applicable on the JDBC resources.
The CMR approach achieves capabilities similar to XA by demanding special database table (normally named xids)
that is accessible for transaction manager to write and to read via the configured CMR datasource.
Let's demonstrate the CMR behavior at the example (reusing setup from the previous one).
- updating the database with
INSERT INTO SQL command, enlisting the CMR resource under the transaction
- sending a message to the JMS broker, enlisting the JMS resource to the transaction
- Narayana starts the two phase commit processing
prepare on CMR saves information about prepare to the xids tableprepare is called to JMS XA resource, the transaction log is stored at the JMS broker sidecommit on CMR means calling commit on underlaying non-XA datasourcecommit on JMS XA resource means commit on the XA JMS resource and thus the message being visible at the queue,
the proper transaction log is removed at the JMS broker side- Narayana two phase commit processing ends
From what you can see here the difference from the LRCO example is that the CMR
resource is not ordered as last in the resource processing but it's ordered
as the first one. The CMR prepare does not mean committing the work as in case of the LRCO
but it means saving information about that CMR is considered to be prepared into the database xids table.
As the CMR is ordered as the first resource for processing it's taken as first during the commit phase too. The commit call then means to call commit at the underlying
database connection. The xids table is not cleaned at that phase
and it's normally responsibility of CommitMarkableResourceRecordRecoveryModule
to process the garbage collection of records in the xids table (see more below).
The main fact to understand is that CMR resource is considered as fully prepared
only after the commit is processed (meaning commit on the underlaying non-XA JDBC datasource).
Till that time the transaction is considered as not prepared and will be processed with rollback by the transaction recovery.
NOTE: the term fully prepared considers the standard XA two-phase commit
processing. If the transaction manager finishes with the prepare phase,
aka. prepare is called on all transaction participants, the transaction is counted
as prepared and commit is expected to be called on each participant.
It's important to note that the correct processing of failures in transactions which contain CMR resources
is responsibility of the special periodic recovery module
CommitMarkableResourceRecordRecoveryModule.
It has to be configured as the first in the recovery module list as it needs to check
and eventually process all the XA resources belonging to the transaction which contains the CMR resource
(the recovery modules are processed in the order they were configured). You can check
here how this is set up in WildFly.
The CMR recovery module knows about the existence of the CMR resource from the record saved in the xids table.
From that it's capable to pair all the resources belonging to the same transaction where CMR was involved.
xids: database table to save CMR processing data
As said Narayana needs a special database table (usually named xids)
to save information that CMR was prepared. You may wonder what is content of that table.
The table consists of three columns.
- xid : id of the transaction branch belonging to the CMR resource
- transactionManagerID : id of transaction manager, this serves to distinguish more transaction managers (WildFly servers) working with the same database.
There is a strict rule that each transaction manager must be defined with unique transaction id
(see description of the node-identifer).
- actionuid : global transaction id which unites all the resources belonging to the one particular transaction
LRCO failure case with CMR
In the example, we presented as problematic for LRCO, the container crashed just before prepare phase finished.
In such case, the CMR is not committed yet. The other transaction participants are then rolled-back
as the transaction was not fully prepared. The CMR brings the consistent rollback outcome for all the resources.
Commit markable resource configured in WildFly
We have sketched the principle of the CMR and now it's time to check
how to configure it for your application running at the WildFly application server.
The configuration consists of three steps.
- The JDBC datasource needs to be marked as connectable
- The database, the connectable datasource points to, has to be enriched with the
xids table
where Narayana can saves the data about CMR processing
- Transaction subsystem needs to be configured to be aware of the CMR capable resource
In our example, I use the H2 database as it's good for the showcase. You can find it in quickstart I prepared too. Check out the
https://github.com/jbosstm/quickstart/tree/master/wildfly/commit-markable-resource.
Mark JDBC datasource as connectable
You will mark the resource as connectable when you use attribute connectable="true"
in your datasource declaration in standalone*.xml configuration file.
When you use jboss cli for the app server configuration you will use commands
/subsystem=datasources/data-source=jdbc-cmr:write-attribute(name=connectable, value=true)
:reload
The whole datasource configuration then looks like
<datasource jndi-name="java:jboss/datasources/jdbc-cmr" pool-name="jdbc-cmr-datasource"
enabled="true" use-java-context="true" connectable="true">
<connection-url>jdbc:h2:mem:cmrdatasource</connection-url>
<driver>h2</driver>
<security>
<user-name>sa</user-name>
<password>sa</password>
</security>
</datasource>
When datasource is marked as connectable then the IronJacamar (JCA layer of WildFly)
creates the datasource instance as implementing
org.jboss.tm.ConnectableResource
(defined in the jboss-transaction-spi project).
This resource defines that the class provides method getConnection() throws Throwable.
That's how the transaction manager is capable to obtain the connection to the database
and works with the xids table inside it.
Xids database table creation
The database configured to be connectable has to ensure existence of the xids
before transaction manager starts. As described above the xids
allows to save the cruical information about the non-XA datasource during prepare.
The shape of the SQL command depends on the SQL syntax of the database you use.
The example of the
table cleation commands is (see more commands under this link)
-- Oracle
CREATE TABLE xids (
xid RAW(144), transactionManagerID VARCHAR(64), actionuid RAW(28)
);
CREATE UNIQUE INDEX index_xid ON xids (xid);
-- PostgreSQL
CREATE TABLE xids (
xid bytea, transactionManagerID varchar(64), actionuid bytea
);
CREATE UNIQUE INDEX index_xid ON xids (xid);
-- H2
CREATE TABLE xids (
xid VARBINARY(144), transactionManagerID VARCHAR(64), actionuid VARBINARY(28)
);
CREATE UNIQUE INDEX index_xid ON xids (xid);
I addressed the need of the table definition in the CMR quickstart
by adding the JPA schema generation create script which contains
the SQL to initialize the database.
Transaction manager CMR configuration
The last part is to configure the CMR for the transaction subsystem.
The declaration puts the datasource under the list
JTAEnvironmentBean#commitMarkableResourceJNDINames
which is then used in code of
TransactionImple#createResource.
The xml element used in the transaction subsystem and the jboss cli commands look like
<commit-markable-resources>
<commit-markable-resource jndi-name="java:jboss/datasources/jdbc-cmr"/>
</commit-markable-resources>
/subsystem=transactions/commit-markable-resource="java:jboss/datasources/jdbc-cmr":add()
:reload
CMR configuration options
In addition to such simple CMR declaration, the CMR can be configured
with following parameters
- jndi-name : as it could be seen above the jndi-name is way to point
to the datasource which we mark as CMR ready
- name : defines the name of the table which is used for storing
the CMR state during prepare while used during recovery.
The default value (and we've reffered to it in this way above) is xids
- immediate-cleanup : If configured to true then there is registered
a synchronization
which removes proper value from the
xids
table immediatelly after the transaction is committed.
When synchronization is not set up then the clean-up of the xids
table is responsibility of the recovery by the code at
CommitMarkableResourceRecordRecoveryModule.
It checks about finished xids and it removes those which are free for garbage collection.
The default value is false (using only recovery garbage collection).
- batch-size : This parameter influences the process of the garbage collection
(as described above).
The garbage collection takes finished xids and runs
DELETE
SQL command. The DELETE contains the WHERE xid in (...) clause
with maximum of batch-size entries provided.
When there is still some finished xids left after deletion,
another SQL command is assembled with maximum number of batch-size
entries again.
The default value is 100.
The
commit-markable-resource xml element configured with all the parameters looks like
<subsystem xmlns="urn:jboss:domain:transactions:4.0">
<core-environment>
<process-id>
<uuid/>
</process-id>
</core-environment>
<recovery-environment socket-binding="txn-recovery-environment" status-socket-binding="txn-status-manager"/>
<object-store path="tx-object-store" relative-to="jboss.server.data.dir"/>
<commit-markable-resources>
<commit-markable-resource jndi-name="java:jboss/datasources/jdbc-cmr">
<xid-location name="myxidstable" batch-size="10" immediate-cleanup="true"/>
</commit-markable-resource>
</commit-markable-resources>
</subsystem>
And the jboss cli commands for the same are
/subsystem=transactions/commit-markable-resource="java:jboss/datasources/jdbc-cmr"\
:write-attribute(name=name, value=myxidstable)
/subsystem=transactions/commit-markable-resource="java:jboss/datasources/jdbc-cmr"\
:write-attribute(name=immediate-cleanup, value=true)
/subsystem=transactions/commit-markable-resource="java:jboss/datasources/jdbc-cmr"\
:write-attribute(name=batch-size, value=10)
:reload
NOTE: the JBoss EAP documentation about the CMR resource configuration can be found
at section
About the LRCO Optimization for Single-phase Commit (1PC)
Conclusion
The article explained what is the Narayana Commit Markable resource (CMR),
it compared it with LRCO and presented its advantages. In the latter part of the article
you found how to configure the CMR resource in your application deployed at the WildFly application server.
If you like to run an application using the commit markable resource feature,
check our Narayana quickstart at
https://github.com/jbosstm/quickstart/tree/master/wildfly/commit-markable-resource.
