Red Hat

Developer Materials

jts: Java Transaction Service - Distributed EJB Transactions

What is it?

The jts quickstart demonstrates how to perform distributed transactions across multiple containers in an application deployed to Red Hat JBoss Enterprise Application Platform. A distributed transaction is a set of operations performed by two or more nodes, participating in an activity coordinated as a single entity of work, and fulfilling the properties of an ACID transaction.

ACID is a set of 4 properties that guarantee the resources are processed in the following manner:

  • Atomic - if any part of the transaction fails, all resources remain unchanged.
  • Consistent - the state will be consistent across resources after a commit
  • Isolated - the execution of the transaction for each resource is isolated from each others
  • Durable - the data will persist after the transaction is committed

The example uses Java Transaction Service (JTS) to propagate a transaction context across two Container-Managed Transaction (CMT) EJBs that, although deployed in separate servers, participate in the same transaction. In this example, one server processes the Customer and Account data and the other server processes the Invoice data.

The code base is essentially the same as the cmt quickstart, however in this case the InvoiceManager has been separated to a different deployment archive to demonstrate the usage of JTS. You can see the changes in the following ways:

  1. cmt/src/main/java/org/jboss/as/quickstarts/cmt/ejb/InvoiceManagerEJB.java has been moved to application-component-2/src/main/java/org/jboss/as/quickstarts/cmt/jts/ejb/InvoiceManagerEJB
  2. cmt/src/main/java/org/jboss/as/quickstarts/cmt/ejb/CustomerManagerEJB.java has been moved to jts/application-component-1/src/main/java/org/jboss/as/quickstarts/cmt/jts/ejb/CustomerManagerEJB.java

The changes to CustomerManagerEJB are purely to accommodate the fact that InvoiceManager is now distributed.

You will see that the CustomerManagerEJB uses the EJB home for the remote EJB, this is expected to connect to remote EJBs. The example expects the EJBs to be deployed onto the same physical machine. This is not a restriction of JTS and the example can easily be converted to run on separate machines by editing the hostname value for the InvoiceManagerEJB in org.jboss.as.quickstarts.cmt.jts.ejb.CustomerManagerEJB.

A simple MDB has been provided that prints out the messages sent but this is not a transactional MDB and is purely provided for debugging purposes.

Also, while the cmt quickstart uses the Java EE container default datasource, which is not distributed, this quickstart instead uses an external PostgreSQL database.

After you complete this quickstart, you are invited to run through the jts-distributed-crash-rec quickstart. The crash recovery quickstart builds upon this quickstart by demonstrating the fault tolerance of Red Hat JBoss Enterprise Application Platform.

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP 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 Red Hat JBoss Enterprise Application Platform.

System requirements

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7 or later.

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

Use of EAP7_HOME

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

Prerequisites

Developers should be familiar with the concepts introduced in the cmt quickstart.

This quickstart requires the configuration of two servers. The first server must be configured to use the PostgreSQL database. Instructions to install and configure PostgreSQL are below.

Configure the PostgreSQL Database for Use with this Quickstart

This quickstart requires the PostgreSQL database.

Instructions to install and configure PostgreSQL can be found here: Download and Install PostgreSQL

Note: For the purpose of this quickstart, replace the word QUICKSTART_DATABASE_NAME with jts-quickstart-database in the PostgreSQL instructions.

Be sure to Create a Database User for the PostgeSQL database.

When you have completed these steps, be sure to start the PostgreSQL database. Unless you have set up the database to automatically start as a service, you must repeat the instructions "Start the database server" for your operating system every time you reboot your machine.

Wait until later in these instructions to add the PostgreSQL module and driver configuration to the first JBoss EAP server.

Configure the JBoss EAP Servers

For this example, you will need two instances of the application server, with a subtle startup configuration difference. Application server 2 must be started up with a port offset parameter provided to the startup script as "-Djboss.socket.binding.port-offset=100".

Since both application servers must be configured in the same way, you must configure the first server and then clone it. After you clone the second server, the first server must be configured for PostgreSQL.

Note: This quickstart README file use the following replaceable values. When you encounter these values in a README file, be sure to replace them with the actual path to the correct JBoss EAP server.

  • EAP7_HOME denotes the path to the original JBoss EAP installation.
  • EAP7_HOME_1 denotes the path to the modified JBoss EAP server 1 configuration.
  • EAP7_HOME_2 denotes the path to the modified JBoss EAP server 2 configuration.

Configure the First Server

You configure JTS transactions by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-jts-transactions.cli script provided in the root directory of this quickstart.

  1. Before you begin, back up your server configuration file
    • If it is running, stop the JBoss EAP server.
    • Backup the file: EAP7_HOME/standalone/configuration/standalone-full.xml
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
  2. Start the JBoss EAP server with the full profile, passing a unique node ID by typing the following command. Be sure to replace UNIQUE_NODE_ID_1 with a node identifier that is unique to both servers.

     For Linux:  EAP7_HOME/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
     For Windows:  EAP7_HOME\bin\standalone.bat -c standalone-full.xml  -Djboss.tx.node.id=UNIQUE_NODE_ID_1
    
  3. Review the configure-jts-transactions.cli file in the root of this quickstart directory. This script configures the server to use jts transaction processing.
  4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

     For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-jts-transactions.cli
     For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-jts-transactions.cli  You should see the following result when you run the script:
    
     process-state: restart-required 
     {
     "outcome" => "success",
     "result" => undefined
     }
    
  5. Stop the JBoss EAP server.

NOTE: When you have completed testing this quickstart, it is important to Remove the JTS Configuration from the JBoss EAP Server.

Review the Modified Server Configuration

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone-full.xml file and review the changes.

  1. The orb initializers transactions attribute is changed from "spec" to "full" in the iiop-openjdk subsystem to enable JTS.

     <subsystem xmlns="urn:jboss:domain:iiop-openjdk:1.0">
         <initializers transactions="full" security="identity"/>
     </subsystem>
    
  2. An empty <jts/> element is added to the the end of the transactions subsystem to enable JTS.

     <subsystem xmlns="urn:jboss:domain:transactions:3.0">
         <core-environment node-identifier="${jboss.tx.node.id}">
             <process-id>
                 <uuid/>
             </process-id>
         </core-environment>
         <recovery-environment socket-binding="txn-recovery-environment" status-socket-binding="txn-status-manager"/>
         <jts/>
     </subsystem>
    

NOTE: When you have completed testing this quickstart, it is important to Remove the JTS Configuration from the JBoss EAP Server.

Clone the EAP7_HOME Directory

Make a copy of this JBoss EAP directory structure to use for the second server.

Configure Server1 to use PostgreSQL

Application server 1 must be now configured to use the PostgreSQL database created previously in the Configure the PostgreSQL Database for Use with this Quickstart section.

  1. Be sure to start the PostgreSQL database. Unless you have set up the database to automatically start as a service, you must repeat the instructions "Start the database server" for your operating system every time you reboot your machine.
  2. Follow the instructions to Add the PostgreSQL Module to the JBoss EAP Server to the server 1 install only.
  3. Follow the instructions to Configure the PostgreSQL Driver in the JBoss EAP Server for the server 1 configuration. Be sure to pass the -Djboss.tx.node.id=UNIQUE_NODE_ID_1 on the command line when you start the first server to configure PostgreSQL.

Start the JBoss EAP Servers

Start the the two JBoss EAP servers with the full profile, passing a unique node ID by typing the following command. You must pass a socket binding port offset on the command to start the second server. Be sure to replace UNIQUE_NODE_ID with a node identifier that is unique to both servers.

If you are using Linux:

    Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
    Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100

If you are using Windows

    Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
    Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100

Build and Deploy the Quickstart

Since this quickstart builds two separate components, you can not use the standard Build and Deploy commands used by most of the other quickstarts. You must follow these steps to build, deploy, and run this quickstart.

  1. Make sure you have started the JBoss EAP server with the PostgreSQL driver
  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 application-component-1/target/jboss-jts-application-component-1.war and application-component-2/target/jboss-jts-application-component-2.jar to the running instance of the server.

Access the application

The application will be running at the following URL: http://localhost:8080/jboss-jts-application-component-1/.

When you enter a name and click to "Add" that customer, you will see the following in the application server 1 console:

INFO  [org.hibernate.hql.internal.QueryTranslatorFactoryInitiator] (default task-2) HHH000397: Using ASTQueryTranslatorFactory
INFO  [org.jboss.ejb.client] (default task-4) JBoss EJB Client version 2.1.4.Final-redhat-1

You will also see the following in application-server-2 console:

INFO  [org.jboss.ejb.client] (p: default-threadpool; w: Idle) JBoss EJB Client version 2.1.4.Final-redhat-1
INFO  [class org.jboss.as.quickstarts.cmt.jts.mdb.HelloWorldMDB] (Thread-97 (ActiveMQ-client-global-threads-6840624)) Received Message: Created invoice for customer named: Tom

The web page will also change and show you the new list of customers.

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.

Undeploy the Archive

  1. Make sure you have started the JBoss EAP 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 package wildfly:undeploy
    

Remove the JTS Configuration from the JBoss EAP Server

You must remove the JTS server configuration you did during setup because it interferes with the JTA quickstarts.

You can modify the server configuration by running the remove-jts-transactions.cli script provided in the root directory of this quickstart, by using the JBoss CLI interactively, or by manually editing the configuration file.

Remove the JTS Server Configuration by Running the JBoss CLI Script

  1. Start the JBoss EAP server with the full profile.

     For Linux:  EAP7_HOME_1/bin/standalone.sh -c standalone-full.xml  -Djboss.tx.node.id=UNIQUE_NODE_ID_1
     For Windows:  EAP7_HOME_1\bin\standalone.bat -c standalone-full.xml  -Djboss.tx.node.id=UNIQUE_NODE_ID_1
    
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

     For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=remove-jts-transactions.cli 
     For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=remove-jts-transactions.cli  This script removes the JTS configuration from the `iiop-openjdk` and `transactions` subsystems in the server configuration. You should see the following result when you run the script:
    
     The batch executed successfully
     process-state: restart-required 
     {
         "outcome" => "success",
         "result" => undefined
     }
    

Remove the JTS Server Configuration using the JBoss CLI Tool

  1. Start the JBoss EAP server with the full profile.

     For Linux:  EAP7_HOME_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
     For Windows:  EAP7_HOME_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
    
  2. To start the JBoss CLI tool, open a new command prompt, navigate to the EAP7_HOME directory, and type the following:

     For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect
     For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect
    
  3. At the prompt, type the following:

     /subsystem=iiop-openjdk/:write-attribute(name=transactions,value=spec)
     /subsystem=transactions/:undefine-attribute(name=jts)
     /subsystem=transactions/:undefine-attribute(name=node-identifier)  You should see the following result when you run the script:
    
     {
         "outcome" => "success",
         "response-headers" => {
             "operation-requires-reload" => true,
             "process-state" => "restart-required"
         }
     }
    
     {
    
         "outcome" => "success",
         "response-headers" => {
             "operation-requires-restart" => true,
             "process-state" => "restart-required"
         }
     }
    
     {
         "outcome" => "success",
         "response-headers" => {
             "operation-requires-reload" => true,
             "process-state" => "restart-required"
         }
     }
    

Remove the JTS Server Configuration Manually

  1. Stop the server.
  2. If you backed up the EAP7_HOME/standalone/configuration/standalone-full.xml,simply replace the edited configuration file with the backup copy.
  3. If you did not make a backup copy, open the file EAP7_HOME/standalone/configuration/standalone-full.xml and disable JTS as follows:

    • Find the orb subsystem and change the configuration back to its original state.

        <subsystem xmlns="urn:jboss:domain:iiop-openjdk:1.0">
            <initializers transactions="spec" security="identity"/>
        </subsystem>
      
    • Find the transaction subsystem and remove the node-identifier attribute from the core-environment element. Also remove the <jts/> element.

        <subsystem xmlns="urn:jboss:domain:transactions:3.0">
            <core-environment>
                <process-id>
                    <uuid/>
                </process-id>
            </core-environment>
            <recovery-environment socket-binding="txn-recovery-environment" status-socket-binding="txn-status-manager"/>
        </subsystem>
      

Recent Changelog

  • Mar 29, 2016(Sande Gilda):JBEAP 3982 Update jts README file with new CLI script and tool output results
  • Mar 4, 2016(Sande Gilda):JBEAP 3672 Update jts instructions to create a database user. Also fixed output of batch command
  • Feb 9, 2016(Sande Gilda):JBEAP 3299 Update jts and jts distributed crash rec README files for replacement of jacorb with iiop openjdk
  • Jan 13, 2016(Sande Gilda):JBEAP 787 Update README file datasource reference pointer to the documentation
  • Dec 22, 2015(Sande Gilda):JBEAP 787 Update JBoss EAP documentation links for JBoss EAP 7
  • Oct 27, 2015(Sande Gilda):JBEAP 1659 Fix jts instructions for removal of configuration
  • Oct 6, 2015(Sande Gilda):JBEAP 918 Add instructions to pass node ID when configuring PostgreSQL for the jts quickstart
  • Oct 5, 2015(Sande Gilda):JBEAP 918 Add the node ID argument to all the JBoss EAP start commands
  • Oct 5, 2015(Sande Gilda):JBEAP 1232 Update JBoss EJB Client version
  • Oct 1, 2015(Sande Gilda):JBEAP 915 Fix configuration changes in jts README file
Avg:
Your Rating:
×