jta-crash-rec: Example of JTA Crash Recovery

Author: Mike Musgrove
Level: Advanced
Technologies: JTA, Crash Recovery
Summary: The jta-crash-rec quickstart uses JTA and Byteman to show how to code distributed (XA) transactions in order to preserve ACID properties on server crash.
Target Product: WildFly
Source: https://github.com/wildfly/quickstart/

What is it?

The jta-crash-rec quickstart demonstrates how to code distributed or XA (eXtended Architecture) transactions so that the ACID properties are preserved across participating resources deployed to WildFly Application Server after a server crash. An XA transaction is one in which multiple resources, such as MDBs and databases, participate within the same transaction. It ensures all operations are performed as a single entity of work. ACID is a set of 4 properties that guarantee the resources are processed in the following manner:

This quickstart shows how to atomically update multiple resources within one transaction. It updates a relational database table using JPA and sends a message using JMS. This type of paired updates to two different resources are called XA transactions and are defined by the Java EE JTA specification JSR-907. JTA transactions are not distributed across multiple application servers.

The relational database table in this example contains two columns that represent a key / value pair. The application presents an HTML form containing two input text boxes and allows you to create, update, delete or list these pairs. When you add or update a key / value pair, the quickstart starts a transaction, updates the database table, produces a JMS message containing the update, and then commits the transaction. If all goes well, eventually the consumer gets the message and generates a database update, setting the value corresponding to the key to something that indicates it was changed by the message consumer.

In this example, you halt the WildFly server in the middle of an XA transaction after the database modification has been committed, but before the JMS producer is committed. You can verify that the transaction was started, then restart the WildFly server to complete the transaction. You then verify that everything is in a consistent state.

WildFly ships with H2, an in-memory database written in Java. In this example, we use H2 for the database. Although H2 XA support is not recommended for production systems, the example does illustrate the general steps you need to perform for any datasource vendor. This example provides its own H2 XA datasource configuration. It is defined in the jta-crash-rec-ds.xml file in the WEB-INF folder of the WAR archive.

Note: This quickstart uses the H2 database included with WildFly Application Server 11. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in WildFly and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for WildFly Application Server.

System Requirements

The application this project produces is designed to be run on WildFly Application Server 11 or later.

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for WildFly 11 to make sure you are configured correctly for testing the quickstarts.

Use of WILDFLY_HOME

In the following instructions, replace WILDFLY_HOME with the actual path to your WildFly installation. The installation path is described in detail here: Use of WILDFLY_HOME and JBOSS_HOME Variables.

Download and Configure Byteman

This quickstart uses Byteman to help demonstrate crash recovery. You can find more information about Byteman here: Configure Byteman for Use with the Quickstarts

Follow the instructions here to download and configure Byteman: Download and Configure Byteman

Configure the Server

NOTE: The Byteman scripts only work in JTA mode. They do not work in JTS mode. If you have configured the server for a quickstart that uses JTS, you must follow the quickstart instructions to remove the JTS configuration from the WildFly server before making the following changes. Otherwise Byteman will not halt the server.

Start the Server

Start the WildFly Server with the Full Profile

  1. Open a command prompt and navigate to the root of the WildFly directory.
  2. The following shows the command line to start the WildFly server with the full profile:
    For Linux:   WILDFLY_HOME/bin/standalone.sh -c standalone-full.xml
    For Windows: WILDFLY_HOME\bin\standalone.bat -c standalone-full.xml
    

Build and Deploy the Quickstart

  1. Make sure you have started the WildFly server as described above.
  2. Open a command prompt and navigate to the root directory of this quickstart.
  3. Type this command to build and deploy the archive:
    mvn clean install wildfly:deploy
    
  4. This will deploy target/jta-crash-rec.war to the running instance of the server.

Access the Application

The application will be running at the following URL: http://localhost:8080/jta-crash-rec/XA.

Test the Application

  1. When you access the application, you will find a web page containing two html input boxes for adding key / value pairs to a database. Instructions for using the application are shown at the top of the application web page.

  2. When you add a new key / value pair, the change is committed to the database and a JMS message sent. The message consumer then updates the newly inserted row by appending the text updated via JMS to the value. Since the consumer updates the row asynchronously, you may need to click Refresh Table to see the text added to the key / value pair you previously entered.

  3. When an XA transaction is committed, the application server completes the transaction in two phases.

  4. To demonstrate XA recovery, you must enable the Byteman tool to terminate the application server while phase 2 is running as follows:

  5. Once you complete step 4, you are ready to create a recovery record. Go to the application URL http://localhost:8080/jta-crash-rec/XA and insert another row into the database. At this point, Byteman halts the application server.

  6. If you want to verify the database insert was committed but that message delivery is still pending, you can use an SQL client such as the H2 database console tool. Issue a query to show that the value is present but does not contain the message added by the consumer (updated via JMS). Here is how you can do it using H2:

  7. To observe XA recovery
  8. Do NOT forget to Disable the Byteman script by restoring the backup server configuration file. The Byteman rule must be removed to ensure that your application server will be able to commit 2PC transactions!

Server Log: Expected Warnings and Errors

Note: You will see the following warnings in the server log. You can ignore these warnings.

WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
HHH000431: Unable to determine H2 database version, certain features may not work

Undeploy the Archive

  1. Make sure you have started the WildFly server as described above.
  2. Open a command prompt and navigate to the root directory of this quickstart.
  3. When you are finished testing, type this command to undeploy the archive:
    mvn wildfly:undeploy
    

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a WildFly server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

NOTE: Within JBoss Developer Studio, be sure to define a server runtime environment that uses the standalone-full.xml configuration file.

Debug the Application

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

    mvn dependency:sources