Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

12.6. Transaction Subsystem Configuration

12.6.2. Transactional Datasource Configuration 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, “Datasource Parameters”.

Your XA Datasource is configured and ready to use. Create a Non-XA Datasource with the Management Interfaces


This topic covers the steps required to create a non-XA datasource, using either the Management Console or the Management CLI.


  • The JBoss EAP 6 server must be running.


Prior to version 10.2 of the Oracle datasource, the <no-tx-separate-pools/> parameter was required, as mixing non-transactional and transactional connections would result in an error. This parameter may no longer be required for certain applications.


To prevent issues such as duplication of driver listing, selected driver not available in a profile, or driver not displayed if a server for the profile is not running, in JBoss EAP 6.4 onwards, only JDBC drivers that are installed as modules and correctly referenced from profiles are detectable while creating a datasource using the Management Console in domain mode.

Procedure 12.1. Create a Datasource using either the Management CLI or the Management Console

    • Management CLI

      1. Launch the CLI tool and connect to your server.
      2. Run the following Management CLI command to create a non-XA datasource, configuring the variables as appropriate:


        The value for DRIVER_NAME depends on the number of classes listed in the /META-INF/services/java.sql.Driver file located in the JDBC driver JAR. If there is only one class, the value is the name of the JAR. If there are multiple classes, the value is the name of the JAR + driverClassName + "_" + majorVersion +"_" + minorVersion. Failure to do so will result in the following error being logged:
        JBAS014775:    New missing/unsatisfied dependencies
        For example, the DRIVER_NAME value required for the MySQL 5.1.31 driver, is mysql-connector-java-5.1.31-bin.jarcom.mysql.jdbc.Driver_5_1.
        data-source add --name=DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME  --connection-url=CONNECTION_URL
      3. Enable the datasource:
        data-source enable --name=DATASOURCE_NAME
    • Management Console

      1. Login to the Management Console.
      2. Navigate to the Datasources panel in the Management Console

        1. Select the Configuration tab from the top of the console.
        2. For Domain mode only, select a profile from the drop-down box in the top left.
        3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
        4. Select Datasources from the menu on the left of the console.
      3. Create a new datasource

        1. Click Add at the top of the Datasources panel.
        2. Enter the new datasource attributes in the Create Datasource wizard and proceed with the Next button.
        3. Enter the JDBC driver details in the Create Datasource wizard and click Next to continue.
        4. Enter the connection settings in the Create Datasource wizard.
        5. Click the Test Connection button to test the connection to the datasource and verify the settings are correct.
        6. Click Done to finish

The non-XA datasource has been added to the server. It is now visible in either the standalone.xml or domain.xml file, as well as the management interfaces. 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 12.2. 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. Configure Database Connection Validation Settings


Database maintenance, network problems, or other outage events may cause JBoss EAP 6 to lose the connection to the database. You enable database connection validation using the <validation> element within the <datasource> section of the server configuration file. Follow the steps below to configure the datasource settings to enable database connection validation in JBoss EAP 6.

Procedure 12.3. Configure Database Connection Validation Settings

  1. Choose a Validation Method

    Select one of the following validation methods.
    • <validate-on-match>true</validate-on-match>

      When the <validate-on-match> option is set to true, the database connection is validated every time it is checked out from the connection pool using the validation mechanism specified in the next step.
      If a connection is not valid, a warning is written to the log and it retrieves the next connection in the pool. This process continues until a valid connection is found. If you prefer not to cycle through every connection in the pool, you can use the <use-fast-fail> option. If a valid connection is not found in the pool, a new connection is created. If the connection creation fails, an exception is returned to the requesting application.
      This setting results in the quickest recovery but creates the highest load on the database. However, this is the safest selection if the minimal performance hit is not a concern.
    • <background-validation>true</background-validation>

      When the <background-validation> option is set to true, it is used in combination with the <background-validation-millis> value to determine how often background validation runs. The default value for the <background-validation-millis> parameter is 0 milliseconds, meaning it is disabled by default. This value should not be set to the same value as your <idle-timeout-minutes> setting.
      It is a balancing act to determine the optimum <background-validation-millis> value for a particular system. The lower the value, the more frequently the pool is validated and the sooner invalid connections are removed from the pool. However, lower values take more database resources. Higher values result in less frequent connection validation checks and use less database resources, but dead connections are undetected for longer periods of time.


    If the <validate-on-match> option is set to true, the <background-validation> option should be set to false. The reverse is also true. If the <background-validation> option is set to true, the <validate-on-match> option should be set to false.
  2. Choose a Validation Mechanism

    Select one of the following validation mechanisms.
    • Specify a <valid-connection-checker> Class Name

      This is the preferred mechanism as it optimized for the particular RDBMS in use. JBoss EAP 6 provides the following connection checkers:
      • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
    • Specify SQL for <check-valid-connection-sql>

      You provide the SQL statement used to validate the connection.
      The following is an example of how you might specify a SQL statement to validate a connection for Oracle:
      <check-valid-connection-sql>select 1 from dual</check-valid-connection-sql>
      For MySQL or PostgreSQL, you might specify the following SQL statement:
      <check-valid-connection-sql>select 1</check-valid-connection-sql>
  3. Set the <exception-sorter> Class Name

    When an exception is marked as fatal, the connection is closed immediately, even if the connection is participating in a transaction. Use the exception sorter class option to properly detect and clean up after fatal connection exceptions. JBoss EAP 6 provides the following exception sorters:
    • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.informix.InformixExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter Datasource Parameters

Table 12.1. Datasource parameters common to non-XA and XA datasources

Parameter Description
jndi-name The unique JNDI name for the datasource.
pool-name The name of the management pool for the datasource.
enabled Whether or not the datasource is enabled.
Whether to bind the datasource to global JNDI.
Enable spy functionality on the JDBC layer. This logs all JDBC traffic to the datasource. Note that the logging category jboss.jdbc.spy must also be set to the log level DEBUG in the logging subsystem.
use-ccm Enable the cached connection manager.
new-connection-sql A SQL statement which executes when the connection is added to the connection pool.
One of the following:
url-selector-strategy-class-name A class that implements interface org.jboss.jca.adapters.jdbc.URLSelectorStrategy.
Contains child elements which are security settings. See Table 12.6, “Security parameters”.
Contains child elements which are validation settings. See Table 12.7, “Validation parameters”.
Contains child elements which are timeout settings. See Table 12.8, “Timeout parameters”.
Contains child elements which are statement settings. See Table 12.9, “Statement parameters”.

Table 12.2. Non-XA datasource parameters

Parameter Description
jta Enable JTA integration for non-XA datasources. Does not apply to XA datasources.
connection-url The JDBC driver connection URL.
driver-class The fully-qualified name of the JDBC driver class.
Arbitrary connection properties passed to the method Driver.connect(url,props). Each connection-property specifies a string name/value pair. The property name comes from the name, and the value comes from the element content.
Contains child elements which are pooling settings. See Table 12.4, “Pool parameters common to non-XA and XA datasources”.
The delimiter for URLs in a connection-url for High Availability (HA) clustered databases.

Table 12.3. XA datasource parameters

Parameter Description
A property to assign to implementation class XADataSource. Specified by name=value. If a setter method exists, in the format setName, the property is set by calling a setter method in the format of setName(value).
The fully-qualified name of the implementation class javax.sql.XADataSource.
A unique reference to the class loader module which contains the JDBC driver. The accepted format is driverName#majorVersion.minorVersion.
Contains child elements which are recovery settings. See Table 12.10, “Recovery parameters”.

Table 12.4. Pool parameters common to non-XA and XA datasources

Parameter Description
min-pool-size The minimum number of connections a pool holds.
max-pool-size The maximum number of connections a pool can hold.
prefill Whether to try to prefill the connection pool. The default is false.
use-strict-min Whether the idle connection scan should strictly stop marking for closure of any further connections, once the min-pool-size has been reached. The default value is false.
Whether the pool is flushed in the case of an error. Valid values are:
  • FailingConnectionOnly
  • IdleConnections
  • EntirePool
The default is FailingConnectionOnly.
allow-multiple-users Specifies if multiple users will access the datasource through the getConnection(user, password) method, and whether the internal pool type accounts for this behavior.

Table 12.5. XA pool parameters

Parameter Description
is-same-rm-override Whether the javax.transaction.xa.XAResource.isSameRM(XAResource) class returns true or false.
interleaving Whether to enable interleaving for XA connection factories.
Whether to create separate sub-pools for each context. This is required for Oracle datasources, which do not allow XA connections to be used both inside and outside of a JTA transaction.
Using this option will cause your total pool size to be twice max-pool-size, because two actual pools will be created.
pad-xid Whether to pad the Xid.
Whether to wrap the XAResource in an instance.

Table 12.6. Security parameters

Parameter Description
user-name The username to use to create a new connection.
password The password to use to create a new connection.
security-domain Contains the name of a JAAS security-manager which handles authentication. This name correlates to the application-policy/name attribute of the JAAS login configuration.
reauth-plugin Defines a reauthentication plug-in to use to reauthenticate physical connections.

Table 12.7. Validation parameters

Parameter Description
An implementation of interface org.jboss.jca.adaptors.jdbc.ValidConnectionChecker which provides a SQLException.isValidConnection(Connection e) method to validate a connection. An exception means the connection is destroyed. This overrides the parameter check-valid-connection-sql if it is present.
check-valid-connection-sql An SQL statement to check validity of a pool connection. This may be called when a managed connection is taken from a pool for use.
Indicates whether connection level validation is performed when a connection factory attempts to match a managed connection for a given set.
Specifying "true" for validate-on-match is typically not done in conjunction with specifying "true" for background-validation. Validate-on-match is needed when a client must have a connection validated prior to use. This parameter is false by default.
Specifies that connections are validated on a background thread. Background validation is a performance optimization when not used with validate-on-match. If validate-on-match is true, using background-validation could result in redundant checks. Background validation does leave open the opportunity for a bad connection to be given to the client for use (a connection goes bad between the time of the validation scan and prior to being handed to the client), so the client application must account for this possibility.
background-validation-millis The amount of time, in milliseconds, that background validation runs.
If true, fail a connection allocation on the first attempt, if the connection is invalid. Defaults to false.
An instance of org.jboss.jca.adapters.jdbc.StaleConnectionChecker which provides a Boolean isStaleConnection(SQLException e) method. If this method returns true, the exception is wrapped in an org.jboss.jca.adapters.jdbc.StaleConnectionException, which is a subclass of SQLException.
An instance of org.jboss.jca.adapters.jdbc.ExceptionSorter which provides a Boolean isExceptionFatal(SQLException e) method. This method validates whether an exception is broadcast to all instances of javax.resource.spi.ConnectionEventListener as a connectionErrorOccurred message.

Table 12.8. Timeout parameters

Parameter Description
use-try-lock Uses tryLock() instead of lock(). This attempts to obtain the lock for the configured number of seconds, before timing out, rather than failing immediately if the lock is unavailable. Defaults to 60 seconds. As an example, to set a timeout of 5 minutes, set <use-try-lock>300</use-try-lock>.
blocking-timeout-millis The maximum time, in milliseconds, to block while waiting for a connection. After this time is exceeded, an exception is thrown. This blocks only while waiting for a permit for a connection, and does not throw an exception if creating a new connection takes a long time. Defaults to 30000, which is 30 seconds.
The maximum time, in minutes, before an idle connection is closed. If not specified, the default is 30 minutes. The actual maximum time depends upon the idleRemover scan time, which is half of the smallest idle-timeout-minutes of any pool.
Whether to set the query timeout based on the time remaining until transaction timeout. Any configured query timeout is used if no transaction exists. Defaults to false.
query-timeout Timeout for queries, in seconds. The default is no timeout.
allocation-retry The number of times to retry allocating a connection before throwing an exception. The default is 0, so an exception is thrown upon the first failure.
How long, in milliseconds, to wait before retrying to allocate a connection. The default is 5000, which is 5 seconds.
If non-zero, this value is passed to method XAResource.setTransactionTimeout.

Table 12.9. Statement parameters

Parameter Description
Whether to check for unclosed statements when a connection is returned to a pool and a statement is returned to the prepared statement cache. If false, statements are not tracked.

Valid values

  • true: statements and result sets are tracked, and a warning is issued if they are not closed.
  • false: neither statements or result sets are tracked.
  • nowarn: statements are tracked but no warning is issued. This is the default.
prepared-statement-cache-size The number of prepared statements per connection, in a Least Recently Used (LRU) cache.
Whether JBoss EAP should cache, instead of close or terminate, the underlying physical statement when the wrapper supplied to the application is closed by application code. The default is false.

Table 12.10. Recovery parameters

Parameter Description
recover-credential A username/password pair or security domain to use for recovery.
An implementation of the org.jboss.jca.core.spi.recoveryRecoveryPlugin class, to be used for recovery.

12.6.3. Transaction Logging 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, “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 12.11. 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. 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 12.4. 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. Browse and Manage Transactions

The Management CLI supports the ability to browse and manipulate transaction records. This functionality is provided by the interaction between the Transaction Manager and the management API of JBoss EAP 6.
The Transaction Manager stores information about each pending transaction and the participants involved the transaction, in a persistent storage called the object store. The management API exposes the object store as a resource called the log-store. An API operation called probe reads the transaction logs and creates a node for each log. You can call the probe command manually, whenever you need to refresh the log-store. It is normal for transaction logs to appear and disappear quickly.

Example 12.2. Refresh the Log Store

This command refreshes the log store for server groups which use the profile default in a managed domain. For a standalone server, remove the profile=default from the command.

Example 12.3. View All Prepared Transactions

To view all prepared transactions, first refresh the log store (see Example 12.2, “Refresh the Log Store”), then run the following command, which functions similarly to a filesystem ls command.
ls /profile=default/subsystem=transactions/log-store=log-store/transactions
Each transaction is shown, along with its unique identifier. Individual operations can be run against an individual transaction (see Manage a Transaction).

Manage a Transaction

View a transaction's attributes.
To view information about a transaction, such as its JNDI name, EIS product name and version, or its status, use the :read-resource CLI command.
View the participants of a transaction.
Each transaction log contains a child element called participants. Use the read-resource CLI command on this element to see the participants of the transaction. Participants are identified by their JNDI names.
The result may look similar to this:
   "outcome" => "success",
   "result" => {
       "eis-product-name" => "HornetQ",
       "eis-product-version" => "2.0",
       "jndi-name" => "java:/JmsXA",
       "status" => "HEURISTIC",
       "type" => "/StateManager/AbstractRecord/XAResourceRecord"
The outcome status shown here is in a HEURISTIC state and is eligible for recovery. See Recover a transaction. for more details.
In special cases it is possible to create orphan records in the object store, that is XAResourceRecords, which do not have any corresponding transaction record in the log. For example, XA resource prepared but crashed before the TM recorded and is inaccessible for the domain management API. To access such records you need to set management option expose-all-logs to true. This option is not saved in management model and is restored to false when the server is restarted.
/profile=default/subsystem=transactions/log-store=log-store:write-attribute(name=expose-all-logs, value=true)
Delete a transaction.
Each transaction log supports a :delete operation, to delete the transaction log representing the transaction.
Recover a transaction.
Each transaction participant supports recovery via the :recover CLI command.

Recovery of heuristic transactions and participants

  • If the transaction's status is HEURISTIC, the recovery operation changes the state to PREPARE and triggers a recovery.
  • If one of the transaction's participants is heuristic, the recovery operation tries to replay the commit operation. If successful, the participant is removed from the transaction log. You can verify this by re-running the :probe operation on the log-store and checking that the participant is no longer listed. If this is the last participant, the transaction is also deleted.
Refresh the status of a transaction which needs recovery.
If a transaction needs recovery, you can use the :refresh CLI command to be sure it still requires recovery, before attempting the recovery.
View Transaction Statistics

If Transaction Manager statistics are enabled, you can view statistics about the Transaction Manager and transaction subsystem. See Section, “Configure the Transaction Manager” for information about how to enable Transaction Manager statistics.

You can view statistics either via the management console or the Management CLI. In the management console, transaction statistics are available via RuntimeStatusSubsystemsTransactions. Transaction statistics are available for each server in a managed domain. To view the status of a different server, select Change Server in the left-hand menu and select the server from the list.
The following table shows each available statistic, its description, and the Management CLI command to view the statistic.

Table 12.12. Transaction Subsystem Statistics

Statistic Description CLI Command
The total number of transactions processed by the Transaction Manager on this server.
The number of committed transactions processed by the Transaction Manager on this server.
The number of aborted transactions processed by the Transaction Manager on this server.
Timed Out
The number of timed out transactions processed by the Transaction Manager on this server.
Not available in the Management Console. Number of transactions in a heuristic state.
In-Flight Transactions
Not available in the Management Console. Number of transactions which have begun but not yet terminated.
Failure Origin - Applications
The number of failed transactions whose failure origin was an application.
Failure Origin - Resources
The number of failed transactions whose failure origin was a resource.
Participant ID
The ID of the participant.
List of all transactions
The complete list of transactions.