Chapter 19. Transaction Subsystem

19.1. Transaction Subsystem Configuration

19.1.2. Configure the Transaction Manager

You can configure the Transaction Manager (TM) using the web-based Management Console or the command-line Management CLI. For each command or option given, the assumption is made that you are running JBoss EAP 6 as a Managed Domain. If you use a Standalone Server or you want to modify a different profile than default, you may need to modify the steps and commands in the following ways.

Notes about the Example Commands

  • For the Management Console, the default profile is the one which is selected when you first log into the console. If you need to modify the Transaction Manager's configuration in a different profile, select your profile instead of default, in each instruction.
    Similarly, substitute your profile for the default profile in the example CLI commands.
  • If you use a Standalone Server, only one profile exists. Ignore any instructions to choose a specific profile. In CLI commands, remove the /profile=default portion of the sample commands.


In order for the TM options to be visible in the Management Console or Management CLI, the transactions subsystem must be enabled. It is enabled by default, and required for many other subsystems to function properly, so it is very unlikely that it would be disabled.
Configure the TM Using the Management Console

To configure the TM using the web-based Management Console, select the Configuration tab from the top of the screen. If you use a managed domain, choose the correct profile from the Profile selection box at the top left. Expand the Container menu and select Transactions.

Most options are shown in the Transaction Manager configuration page. The Recovery options are hidden by default. Click the Recovery tab to see the recovery options. Click Edit to edit any of the options. Changes take effect immediately.
Click the Need Help? label to display in-line help text.
Configure the TM using the Management CLI

In the Management CLI, you can configure the TM using a series of commands. The commands all begin with /profile=default/subsystem=transactions/ for a managed domain with profile default, or /subsystem=transactions for a Standalone Server.


If transaction subsystem is configured to use hornetq journal as storage type for transaction logs, then two instances of JBoss EAP is not permitted to use the same directory for storing the journal. Application server instances can't share the same location and each has to configure unique location for it.

Table 19.1. TM Configuration Options

Option Description CLI Command
Enable Statistics
Whether to enable transaction statistics. These statistics can be viewed in the Management Console in the Subsystem Metrics section of the Runtime tab.
Enable TSM Status
Whether to enable the transaction status manager (TSM) service, which is used for out-of-process recovery. Running an out of process recovery manager to contact the ActionStatusService from different process is not supported (it is normally contacted in memory).
This configuration option is unsupported.
Default Timeout
The default transaction timeout. This defaults to 300 seconds. You can override this programmatically, on a per-transaction basis.
Object Store Path
A relative or absolute filesystem path where the TM object store stores data. By default relative to the object-store-relative-to parameter's value.
Object Store Path Relative To
References a global path configuration in the domain model. The default value is the data directory for JBoss EAP 6, which is the value of the property, and defaults to EAP_HOME/domain/data/ for a Managed Domain, or EAP_HOME/standalone/data/ for a Standalone Server instance. The value of the object store object-store-path TM attribute is relative to this path.
Socket Binding
Specifies the name of the socket binding used by the Transaction Manager for recovery and generating transaction identifiers, when the socket-based mechanism is used. Refer to process-id-socket-max-ports for more information on unique identifier generation. Socket bindings are specified per server group in the Server tab of the Management Console.
Status Socket Binding
Specifies the socket binding to use for the Transaction Status manager.
This configuration option is unsupported.
Recovery Listener
Whether or not the Transaction Recovery process should listen on a network socket. Defaults to false.
The following options are for advanced use and can only be modified using the Management CLI. Be cautious when changing them from the default configuration. Contact Red Hat Global Support Services for more information.

Table 19.2. Advanced TM Configuration Options

Option Description CLI Command
Whether to use Java Transaction Service (JTS) transactions. Defaults to false, which uses JTA transactions only.
The node identifier for the Transaction Manager. This option is required in the following situations:
  • For JTS to JTS communications
  • When two Transaction Managers access shared resource managers
  • When two Transaction Managers access shared object stores
The node-identifier must be unique for each Transaction Manager as it is required to enforce data integrity during recovery. The node-identifier must also be unique for JTA because multiple nodes may interact with the same resource manager or share a transaction object store.
The Transaction Manager creates a unique identifier for each transaction log. Two different mechanisms are provided for generating unique identifiers: a socket-based mechanism and a mechanism based on the process identifier of the process.
In the case of the socket-based identifier, a socket is opened and its port number is used for the identifier. If the port is already in use, the next port is probed, until a free one is found. The process-id-socket-max-ports represents the maximum number of sockets the TM will try before failing. The default value is 10.
Set to true to use the process identifier to create a unique identifier for each transaction. Otherwise, the socket-based mechanism is used. Defaults to true. Refer to process-id-socket-max-ports for more information. To enable process-id-socket-binding, set process-id-uuid to false.
The name of the socket binding configuration to use if the transaction manager should use a socket-based process id. Will be undefined if process-id-uuid is true; otherwise must be set.
Use HornetQ's journaled storage mechanisms instead of file-based storage, for the transaction logs. This is disabled by default, but can improve I/O performance. It is not recommended for JTS transactions on separate Transaction Managers. When changing this option, the server has to be restarted using the shutdown command for the change to take effect.

19.1.3. Configure Your Datasource to Use JTA Transaction API


This task shows you how to enable Java Transaction API (JTA) on your datasource.


You must meet the following conditions before continuing with this task:

Procedure 19.1. Configure the Datasource to use Java Transaction API

  1. Open the configuration file in a text editor.

    Depending on whether you run JBoss EAP 6 in a managed domain or standalone server, your configuration file will be in a different location.
    • Managed domain

      The default configuration file for a managed domain is in EAP_HOME/domain/configuration/domain.xml for Red Hat Enterprise Linux, and EAP_HOME\domain\configuration\domain.xml for Microsoft Windows Server.
    • Standalone server

      The default configuration file for a standalone server is in EAP_HOME/standalone/configuration/standalone.xml for Red Hat Enterprise Linux, and EAP_HOME\standalone\configuration\standalone.xml for Microsoft Windows Server.
  2. Locate the <datasource> tag that corresponds to your datasource.

    The datasource will have the jndi-name attribute set to the one you specified when you created it. For example, the ExampleDS datasource looks like this:
    <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="H2DS" enabled="true" jta="true" use-java-context="true" use-ccm="true">
  3. Set the jta attribute to true.

    Add the following to the contents of your <datasource> tag, as they appear in the previous step: jta="true"
    Unless you have a specific use case (such as defining a read only datasource) Red Hat discourages overriding the default value of jta=true. This setting indicates that the datasource will honor the Java Transaction API and allows better tracking of connections by the JCA implementation.
  4. Save the configuration file.

    Save the configuration file and exit the text editor.
  5. Start JBoss EAP 6.

    Relaunch the JBoss EAP 6 server.

JBoss EAP 6 starts, and your datasource is configured to use Java Transaction API.

19.1.4. Configure an XA Datasource


Log into the Management Console.

  1. Add a new datasource.

    Add a new datasource to JBoss EAP 6. Click the XA Datasource tab at the top.


    Refer to Create an XA Datasource with the Management Interfaces section of the Administration and Configuration Guide on the Red Hat Customer Portal for information on how to add a new datasource to JBoss EAP 6.
  2. Configure additional properties as appropriate.

    All datasource parameters are listed in Section 6.7.1, “Datasource Parameters”.

Your XA Datasource is configured and ready to use.

19.1.5. About Transaction Log Messages

To track transaction status while keeping the log files readable, use the DEBUG log level for the transaction logger. For detailed debugging, use the TRACE log level. Refer to Section 19.1.6, “Configure Logging for the Transaction Subsystem” for information on configuring the transaction logger.
The transaction manager can generate a lot of logging information when configured to log in the TRACE log level. Following are some of the most commonly-seen messages. This list is not comprehensive, so you may see other messages than these.

Table 19.3. Transaction State Change

Transaction Begin
When a transaction begins, the following code is executed:
tsLogger.logger.trace("BasicAction::Begin() for action-id "+ get_uid());
Transaction Commit
When a transaction commits, the following code is executed:
tsLogger.logger.trace("BasicAction::End() for action-id "+ get_uid());
Transaction Rollback
When a transaction rolls back, the following code is executed:
tsLogger.logger.trace("BasicAction::Abort() for action-id "+ get_uid());
Transaction Timeout
When a transaction times out, the following code is executed:
tsLogger.logger.trace("Reaper Worker " + Thread.currentThread() + " attempting to cancel " + e._control.get_uid());
You will then see the same thread rolling back the transaction as shown above.

19.1.6. Configure Logging for the Transaction Subsystem


Use this procedure to control the amount of information logged about transactions, independent of other logging settings in JBoss EAP 6. The main procedure shows how to do this in the web-based Management Console. The Management CLI command is given afterward.

Procedure 19.2. Configure the Transaction Logger Using the Management Console

  1. Navigate to the Logging configuration area.

    In the Management Console, click the Configuration tab. If you use a managed domain, choose the server profile you wish to configure, from the Profile selection box at the top left.
    Expand the Core menu, and select Logging.
  2. Edit the com.arjuna attributes.

    Select the Log Categories tab. Select com.arjuna and lick Edit in the Details section. This is where you can add class-specific logging information. The com.arjuna class is already present. You can change the log level and whether to use parent handlers.
    Log Level
    The log level is WARN by default. Because transactions can produce a large quantity of logging output, the meaning of the standard logging levels is slightly different for the transaction logger. In general, messages tagged with levels at a lower severity than the chosen level are discarded.

    Transaction Logging Levels, from Most to Least Verbose

    • TRACE
    • DEBUG
    • INFO
    • WARN
    • ERROR
    Use Parent Handlers
    Whether the logger should send its output to its parent logger. The default behavior is true.
  3. Changes take effect immediately.