Red Hat Training

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

6.4. XA Datasources

6.4.1. Create an XA Datasource with the Management Interfaces

Prerequisites:

Summary

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

Note

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.

Procedure 6.9. Create an XA Datasource, Using Either the Management CLI or the Management Console

    • Management CLI

      1. Section 3.4.2, “Launch the Management CLI”.
      2. Run the following Management CLI command to create an XA datasource, configuring the variables as appropriate:

        Note

        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. 
        xa-data-source add --name=XA_DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME --xa-datasource-class=XA_DATASOURCE_CLASS

      3. Configure the XA datasource properties

        1. Set the server name

          Run the following command to configure the server name for the host: 
          /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=ServerName:add(value=HOSTNAME)

        2. Set the database name

          Run the following command to configure the database name: 
          /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=DatabaseName:add(value=DATABASE_NAME)
      4. Enable the datasource: 
        xa-data-source enable --name=XA_DATASOURCE_NAME

    • Management Console

      1. Section 3.3.2, “Log in 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 at the top left.
        3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
        4. Select Datasources.
      3. Select the XA Datasource tab.

      4. Create a new XA datasource

        1. Click Add.
        2. Enter the new XA datasource attributes in the Create XA Datasource wizard and click Next.
        3. Enter the JDBC driver details in the Create XA Datasource wizard and click Next.
        4. Enter the XA properties and click Next.
        5. Enter the connection settings in the Create XA Datasource wizard.
        6. Click the Test Connection button to test the connection to the XA datasource and verify the settings are correct.
        7. Click Done to finish
Result

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

See Also:

Report a bug

6.4.2. Modify an XA Datasource with the Management Interfaces

Summary

This topic covers the steps required to modify an XA datasource, using either the Management Console or the Management CLI.

Prerequisites

Procedure 6.10. Modify an XA Datasource, Using Either the Management CLI or the Management Console

    • Management CLI

      1. Section 3.4.2, “Launch the Management CLI”.

      2. Configure XA datasource attributes

        Use the write-attribute command to configure a datasource attribute: 
        /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME:write-attribute(name=ATTRIBUTE_NAME,value=ATTRIBUTE_VALUE)

      3. Configure XA datasource properties

        Run the following command to configure an XA datasource subresource: 
        /subsystem=datasources/xa-data-source=DATASOURCE_NAME/xa-datasource-properties=PROPERTY_NAME:add(value=PROPERTY_VALUE)
      4. Reload the server to confirm the changes: 
        reload

    • Management Console

      1. Section 3.3.2, “Log in 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 at top left.
        3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
        4. Select Datasources.
      3. Select the XA Datasource tab.

      4. Edit the datasource

        1. Select the relevant XA datasource from the Available XA Datasources list. The XA datasource attributes are displayed in the Attributes panel below it.
        2. Select the Edit button to edit the datasource attributes.
        3. Edit the XA datasource attributes and select the Save button when done.
Result

The XA datasource has been configured. The changes are now visible in either the standalone.xml or domain.xml file, as well as the management interfaces.

Report a bug

6.4.3. Remove an XA Datasource with the Management Interfaces

Summary

This topic covers the steps required to remove an XA datasource from JBoss EAP 6, using either the Management Console or the Management CLI.

Prerequisites

Procedure 6.11. Remove an XA Datasource Using Either the Management CLI or the Management Console

    • Management CLI

      1. Section 3.4.2, “Launch the Management CLI”.
      2. Run the following command to remove an XA datasource: 
        xa-data-source remove --name=XA_DATASOURCE_NAME

    • Management Console

      1. Section 3.3.2, “Log in 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.
      3. Select the XA Datasource tab.
      4. Select the registered XA datasource to be deleted, and click Remove to permanently delete the XA datasource.
Result

The XA datasource has been removed from the server.

Report a bug

6.4.4. XA Recovery

6.4.4.1. About XA Recovery Modules

Each XA resource needs a recovery module associated with its configuration. The recovery module must extend class com.arjuna.ats.jta.recovery.XAResourceRecovery.
JBoss EAP 6 provides recovery modules for JDBC and JMS XA resources. For these types of resources, recovery modules are automatically registered. If you need to use a custom module, you can register it in your datasource.
Report a bug

6.4.4.2. Configure XA Recovery Modules

For most JDBC and JMS resources, the recovery module is automatically associated with the resource. In these cases, you only need to configure the options that allow the recovery module to connect to your resource to perform recovery.
For custom resources which are not JDBC or JMS, contact Red Hat Global Support Services for information on supported configurations.
Each of these configuration attributes can be set either during datasource creation, or afterward. You can set them using either the web-based Management Console or the command-line Management CLI. Refer to Section 6.4.1, “Create an XA Datasource with the Management Interfaces” and Section 6.4.2, “Modify an XA Datasource with the Management Interfaces” for general information on configuring XA datasources.
Refer to the following tables for general datasource configuration attributes, and for information about configuration details relating to specific database vendors.

Table 6.2. General Configuration Attributes

Attribute Description
recovery-username
The username the recovery module should use to connect to the resource for recovery.
recovery-password
The password the recovery module should use to connect to the resource for recovery.
recovery-security-domain
The security domain the recovery module should use to connect to the resource for recovery.
recovery-plugin-class-name
If you need to use a custom recovery module, set this attribute to the fully-qualified class name of the module. The module should extend class com.arjuna.ats.jta.recovery.XAResourceRecovery.
recovery-plugin-properties
If you use a custom recovery module which requires properties to be set, set this attribute to the list of comma-separated key=value pairs for the properties.

Note

The names used in the Table 6.2, “General Configuration Attributes” are parameters which are used when the datasource is configured via CLI. They may differ from names used in XML configuration file.

Vendor-Specific Configuration Information

This section describes specific configurations which are required to be done for particular database to cooperate in XA transactions managed by the JBoss EAP transaction manager. For more detailed information, refer to documentation for a particular database.
Oracle
If the Oracle datasource is configured incorrectly, you may see errors like the following in your log output:

Example 6.11. Incorrect configuration error

WARN  [com.arjuna.ats.jta.logging.loggerI18N] [com.arjuna.ats.internal.jta.recovery.xarecovery1] Local XARecoveryModule.xaRecovery  got XA exception javax.transaction.xa.XAException, XAException.XAER_RMERR
To resolve this error, ensure that the Oracle user configured in recovery-username has access to the tables needed for recovery. The following SQL statement shows the correct grants for Oracle 11g or Oracle 10g R2 instances patched for Oracle bug 5945463.

Example 6.12. Grant configuration

GRANT SELECT ON sys.dba_pending_transactions TO recovery-username;
GRANT SELECT ON sys.pending_trans$ TO recovery-username;
GRANT SELECT ON sys.dba_2pc_pending TO recovery-username;
GRANT EXECUTE ON sys.dbms_xa TO recovery-username;
If you use an Oracle 11 version prior to 11g, change the final EXECUTE statement to the following: 
	GRANT EXECUTE ON sys.dbms_system TO recovery-username;
PostgreSQL and Postgres Plus Advanced Server
For PostgreSQL to be able to handle XA transaction, change the configuration parameter max_prepared_transactions to an value higher than 0.
MySQL
No special configuration is required. For more information, refer to MySQL documentation.
IBM DB2
No special configuration is required. For more information, refer to IBM DB2 documentation.
Sybase
Sybase expects XA transactions to be enabled on the database. Without correct database configuration, XA transactions will not work. enable xact coordination enables or disables Adaptive Server transaction coordination services. When this parameter is enabled, Adaptive Server ensures that updates to remote Adaptive Server data commit or roll back with the original transaction. To enable transaction coordination, use: 
sp_configure 'enable xact coordination', 1
.
MSSQL
For more information, refer to Microsoft documentation. You can also refer http://msdn.microsoft.com/en-us/library/aa342335.aspx as a starting point.

Vendor-specific issues and their consequences

This section describes the currently known database specific issues connected with handling XA transactions. These issues refers to database versions and jdbc drivers which are currently supported by particular EAP version.
Oracle
There are no known issues related to database.
PostgreSQL
  • Jdbc driver returns XAER_RMERR when an error occurs during the call of commit method protocol. Database returns this error code and leaves the transaction in in-doubt state on the database side. The correct return code should be XAER_RMFAIL or XAER_RETRY. For more information, see https://github.com/pgjdbc/pgjdbc/issues/236. This causes the transaction to be left in the Heuristic state on the EAP side and holding locks in database which requires user intervention.
  • The incorrect error code returned by the jdbc driver can cause data inconsistency in some cases. For more information, refer to https://developer.jboss.org/thread/251537, https://github.com/pgjdbc/pgjdbc/issues/236
Postgres Plus Advanced Server
  • Jdbc driver returns XAER_RMERR when an error occurs during the call of commit method protocol. Database returns this error code and leaves the transaction in in-doubt state on the database side. The correct return code should be XAER_RMFAIL or XAER_RETRY. For more information, see https://github.com/pgjdbc/pgjdbc/issues/236. This causes the transaction to be left in the Heuristic state on the EAP side and holding locks in database which requires user intervention.
  • The incorrect error code returned by the jdbc driver can cause data inconsistency in some cases. For more information, refer to https://developer.jboss.org/thread/251537
  • If XAResource.rollback is called for the same XID more than once then XAException is thrown. Calling rollback against the same XID several times is compliant with JTS spec and no XAException should be thrown. For more information, see https://github.com/pgjdbc/pgjdbc/issues/78.
MySQL
MySQL is not capable of handling XA transactions. If a client is disconnected the MySQL then all the information about such transactions is lost. For more information, see http://bugs.mysql.com/bug.php?id=12161.
IBM DB2
There are no known issues related to database.
Sybase
  • Jdbc driver returns XAER_RMERR when an error occurs during the call of commit method protocol. Database returns this error code and leaves the transaction in in-doubt state on the database side. The correct return code should be XAER_RMFAIL or XAER_RETRY. For more information, see https://github.com/pgjdbc/pgjdbc/issues/236. This causes the transaction to be left in the Heuristic state on the EAP side and holding locks in database which requires user intervention.
  • If XAResource.rollback is called for the same XID more than once then XAException is thrown. Calling rollback against the same XID several times is compliant with JTS spec and no XAException should be thrown. For more information, see https://github.com/pgjdbc/pgjdbc/issues/78.
MSSQL
Messaging

IBM Websphere

  • When JTS is used then second call of rollback against the same XID during the periodic recovery can cause an error to be logged in the log file. Second rollback against the same XID is JTS complaint and can be ignored.
    When RAR does not know such XID, then XAER_NOTA return code is expected. But IBM Websphere may return an incorrect return code XAER_RMFAIL. 
    The method 'xa_rollback' has failed with errorCode '-7' due to the resource being closed.'

ActiveMQ

  • Resource adapter returns XAER_RMERR when an error occurs during the call of commit method protocol, for example network disconnection. Resource adapter returns this error code back to transaction manager and it causes the transaction being left in in-doubt state on message broker side. This behaviour is against XA specification and the correct return code should be XAER_RMFAIL or XAER_RETRY. The wrong error code can cause data inconsistency in some cases. For more information, refer to https://developer.jboss.org/thread/251537 . 
    WARN [com.arjuna.ats.jtax] ...: XAResourceRecord.rollback caused an XA error: ARJUNA016099: Unknown error code:0 from resource ...  in transaction ...: javax.transaction.xa.XAException: Transaction ...  has not been started.

TIBCO

  • When JTS is used then second call of rollback against the same XID during the periodic recovery can cause an error to be logged in the log file. Second rollback against the same XID is JTS complaint and can be ignored. 
    WARN [com.arjuna.ats.jtax] ...: XAResourceRecord.rollback caused an XA error: XAException.XAER_RMFAIL from resource ... in transaction ...: javax.transaction.xa.XAException
Report a bug