Chapter 21. Transaction Subsystem

21.1. Transaction Subsystem Configuration

21.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.

Note

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.

Important

HornetQ does not allow multiple instances to share a message log store. If you are configuring multiple instances of HornetQ, each instance must have its own message log store.

Table 21.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.
/profile=default/subsystem=transactions/:write-attribute(name=enable-statistics,value=true)
Default Timeout
The default transaction timeout. This defaults to 300 seconds. You can override this programmatically, on a per-transaction basis.
/profile=default/subsystem=transactions/:write-attribute(name=default-timeout,value=300)
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.
/profile=default/subsystem=transactions/:write-attribute(name=object-store-path,value=tx-object-store)
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 jboss.server.data.dir, 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.
/profile=default/subsystem=transactions/:write-attribute(name=object-store-relative-to,value=jboss.server.data.dir)
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.
/profile=default/subsystem=transactions/:write-attribute(name=socket-binding,value=txn-recovery-environment)
Recovery Listener
Whether or not the Transaction Recovery process should listen on a network socket. Defaults to false.
/profile=default/subsystem=transactions/:write-attribute(name=recovery-listener,value=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 21.2. Advanced TM Configuration Options

Option Description CLI Command
jts
Whether to use Java Transaction Service (JTS) transactions. Defaults to false, which uses JTA transactions only.
/profile=default/subsystem=transactions/:write-attribute(name=jts,value=false)
node-identifier
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.
/profile=default/subsystem=transactions/:write-attribute(name=node-identifier,value=1)
process-id-socket-max-ports
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.
/profile=default/subsystem=transactions/:write-attribute(name=process-id-socket-max-ports,value=10)
process-id-uuid
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.
/profile=default/subsystem=transactions/:write-attribute(name=process-id-uuid,value=true)
use-hornetq-store
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.
/profile=default/subsystem=transactions/:write-attribute(name=use-hornetq-store,value=false)

21.1.3. Configure Your Datasource to Use JTA Transaction API

Summary

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

Prerequisites

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

Procedure 21.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"
  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.
Result:

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

21.1.4. Configure an XA Datasource

Prerequisites

In order to add an XA Datasource, you need to log into the Management Console. See Section 3.4.2, “Log in to the Management Console” for more information.

  1. Add a new datasource.

    Add a new datasource to JBoss EAP 6. Follow the instructions in Section 6.3.1, “Create a Non-XA Datasource with the Management Interfaces”, but click the XA Datasource tab at the top.
  2. Configure additional properties as appropriate.

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

Your XA Datasource is configured and ready to use.

21.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 21.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 21.3. Transaction State Change

Transaction Begin
When a transaction begins, the following code is executed:
com.arjuna.ats.arjuna.coordinator.BasicAction::Begin:1342
tsLogger.logger.trace("BasicAction::Begin() for action-id "+ get_uid());
Transaction Commit
When a transaction commits, the following code is executed:
com.arjuna.ats.arjuna.coordinator.BasicAction::End:1342
tsLogger.logger.trace("BasicAction::End() for action-id "+ get_uid());
Transaction Rollback
When a transaction rolls back, the following code is executed:
com.arjuna.ats.arjuna.coordinator.BasicAction::Abort:1575
tsLogger.logger.trace("BasicAction::Abort() for action-id "+ get_uid());
Transaction Timeout
When a transaction times out, the following code is executed:
com.arjuna.ats.arjuna.coordinator.TransactionReaper::doCancellations:349
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.

21.1.6. Configure Logging for the Transaction Subsystem

Summary

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 21.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
    • FAILURE
    Use Parent Handlers
    Whether the logger should send its output to its parent logger. The default behavior is true.
  3. Changes take effect immediately.