XATransaction

Copyright © Cloud Software Group, Inc. All Rights Reserved

XATransaction

The XA Transaction type allows you to specify an XA-compliant transaction manager provided by a third party that supports the interfaces javax.transaction.TransactionManager and javax.transaction.Transaction. The following XA-compliant transaction managers have been tested with TIBCO ActiveMatrix BusinessWorks:

•

TIBCO BusinessWorks XA Transaction Manager 1.0

•

Arjuna Transaction Service 4.0

•

Java Open Transaction Manager (JOTM) 1.5.3 (this transaction manager does not support transaction recovery)

The XA Transaction type allows JDBC activities, ActiveEnterprise Adapter activities that use the JMS transport, and JMS activities to participate in transactions. Transactions across multiple databases are also supported. Also, if your process engine is configured to use a database for storage of process engine data, checkpoints can participate in an XA Transaction.

For JMS activities and ActiveEnterprise Adapter activities, request/reply operations cannot participate in an XA transaction.

Also, EJB activities cannot participate in an XA Transaction group.

The transaction manager is typically executed in the same Java VM as TIBCO ActiveMatrix BusinessWorks. Because of this, for third-party transaction managers, the path to the files needed to run the transaction manager must be placed in the TIBCO ActiveMatrix BusinessWorks classpath in the bwengine.tra and designer.tra files. For the TIBCO BusinessWorks XA Transaction Manager, configuration occurs during product installation.

If the transaction commits, all eligible activities in the transaction group commit. If the transaction rolls back, all eligible activities in the transaction group roll back. The transaction group commits automatically if all activities in the group complete and a non-error transition is taken out of the transaction group. If any errors occur while processing the activities in the group, even errors in activities that do not participate in the transaction, the transaction is rolled back and an error is returned. You should have an error transition out of the group to handle this situation.

Configuring XA Transactions

To configure an XA Transaction, select XA Transaction as the transaction type of the group.

JDBC Connections used by JDBC activities in the transaction group must be configured to use XA as the connection type. JMS activities must be configured to use the XA connection factory.

The XA Transaction group has the following fields on the transaction group’s Configuration tab:

Field

Description

Transaction Manager

An XA Transaction shared configuration resource. See TIBCO ActiveMatrix BusinessWorks Palette Reference for more information about this resource.

Include In Transaction

Certain resources, such as JMS Queue Receiver, Wait for JMS Queue Message, or JMS Topic Subscriber expect acknowledge messages to be sent to the server. Normally, this is done by using a Confirm activity. These resources can also specify an acknowledge mode of "Transactional" that specifies their acknowledgement should be part of a transaction.

This field allows you to specify the resource for which you would like to send an acknowledgement message. This message is part of the transaction, if the transaction completes successfully. There is no need for a Confirm activity for the resources specified in this field.

Note: Transactional acknowledge mode is not supported for Wait for JMS Topic Message activities.

Include Checkpoint

When this field is checked, an implicit checkpoint is performed after the last activity in the group completes successfully and before the transaction is committed. The deployment configuration must specify a database for storing process engine information and the JDBC Connection used must specify XA as the connection type for this checkpoint to participate in the transaction.

Checkpoint Duplicate Key

When the Include Checkpoints field is checked, you can specify a duplicate key in this field to perform duplicate checking. This is useful if the checkpoint included in the transaction is the first checkpoint in the process definition. If the process engine crashes after the checkpoint, restarted process instances can use the duplicate key to determine if the transaction has already occurred. See Detecting Duplicate Process Instances for more information about specifying duplicate keys.

Configuring Transaction Managers

When using a transaction manager with TIBCO ActiveMatrix BusinessWorks, you must configure the transaction manager and TIBCO ActiveMatrix BusinessWorks to work together properly. This section details the requirements for configuring the supported transaction managers.

TIBCO BusinessWorks XA Transaction Manager

The TIBCO BusinessWorks XA Transaction Manager is automatically configured for use with TIBCO ActiveMatrix BusinessWorks. However, in case TIBCO BusinessWorks XA Transaction Manager does not configure automatically, you can configure it manually.

To configure the BusinessWorks XA Transaction Manager manually, append the following paths to the tibco.env.CUSTOM_EXT_APPEND_CP property in bwengine.tra and designer.tra files:

<TIBCO_HOME>/bw/tm/1.0/lib

<TIBCO_HOME>/bw/tm/1.0/lib/ext

You may wish to set some of the custom engine properties available for this transaction manager. See TIBCO ActiveMatrix BusinessWorks Administration for more information about custom engine properties.

Java Open Transaction Manager (JOTM)

For Java Open Transaction Manager (JOTM), no changes are required to the JOTM environment to interact with TIBCO ActiveMatrix BusinessWorks. However, TIBCO ActiveMatrix BusinessWorks must be configured as follows to interact with JOTM.

1.

The classpath for TIBCO Designer and TIBCO ActiveMatrix BusinessWorks must be modified to include the JOTM jar files. To accomplish this, the following JOTM directory must be included in classpath properties in the designer.tra and bwengine.tra files:

   <JOTM_HOME>\jotm-1.5.3\config

   <JOTM_HOME>\jotm-1.5.3\lib

2.

The logging details for JOTM is specified in the TIBCO ActiveMatrix BusinessWorks log4j property file (<BW_HOME>\5.12\lib\log4j.properties). By default, the log4j property file is configured to send JOTM log messages to the TIBCO ActiveMatrix BusinessWorks log file (BWLogFileAppender).

To send JOTM log messages to a separate file, you must modify the TIBCO ActiveMatrix BusinessWorks log4j property file. There are several JOTM logger properties with the prefix, log4j.logger.org.objectweb.jotm. To each of these properties, add jotm_log_file.

See Logging for Third-Party Components for more information about the TIBCO ActiveMatrix BusinessWorks log4j file.

Arjuna Transaction Service

For the Arjuna Transaction Service (ATS), both the ATS environment and the TIBCO ActiveMatrix BusinessWorks environment must be modified.

The following configuration changes must be performed in the ATS properties file:

1.

ATS provides two transaction manager implementations, one that is local (com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple) and one that is based on the distributed JTA implementation (com.arjuna.ats.internal.jta.transaction.jts.TransactionManagerImple). TIBCO ActiveMatrix BusinessWorks only supports the local implementations. For TIBCO ActiveMatrix BusinessWorks to work correctly, ATS must be configured to use the local implementations. Open the ATS properties file (<ATS_HOME>\ats-4.0\etc\arjunajts-properties.xml) and make sure that the properties com.arjuna.ats.jta.jtaTMImplementation and com.arjuna.ats.jta.jtaUTImplementation are set to the following values:

<property name="com.arjuna.ats.jta.jtaTMImplementation" value="com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple"/>

<property name="com.arjuna.ats.jta.jtaUTImplementation" value="com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple"/>

2.

ATS provides two recovery modules for XA resources, one for local transaction recovery and one for distributed transaction recovery. In TIBCO ActiveMatrix BusinessWorks, local transaction recovery is used. By default the ATS properties file may be configured to enable both the local transaction recovery (<property name="com.arjuna.ats.arjuna.recovery.recoveryExtension5" value="com.arjuna.ats.internal.jta.recovery.arjunacore.XARecoveryModule"/>) and distributed transaction recovery (<property name="com.arjuna.ats.arjuna.recovery.recoveryExtension6" value="com.arjuna.ats.internal.jta.recovery.jts.XARecoveryModule"/>).

TIBCO ActiveMatrix BusinessWorks uses the local transaction recovery, therefore the distributed transaction recovery property must be commented out or removed from the ATS properties file.

3.

By default, the ATS ObjectStore is created in the current working directory of the application. When using TIBCO ActiveMatrix BusinessWorks, this will be the working directory or the directory where the TIBCO ActiveMatrix BusinessWorks process engine is started. It is recommended that you change the location where the ATS ObjectStore is created. To change the object store's location, set the value for the following property in the ATS properties file to your directory’s location:

   <property

   name="com.arjuna.ats.arjuna.objectstore.objectStoreDir"

   value="your directory location" />

The following configuration changes must be made to TIBCO ActiveMatrix BusinessWorks to interact with ATS:

1.

The classpath for TIBCO Designer and TIBCO ActiveMatrix BusinessWorks must be modified to include the ATS property file and jar files. To accomplish this, the following directories must be included in classpath properties in the designer.tra and bwengine.tra files:

   <ATS_HOME>\ats-4.0\etc

   <ATS_HOME>\ats-4.0\lib

   <ATS_HOME>\ats-4.0\lib\ext

2.

The logging details for ATS is specified in the TIBCO ActiveMatrix BusinessWorks log4j property file (<BW_HOME>\5.12\lib\log4j.properties). By default, the log4j property file is configured to send ATS log messages to the TIBCO ActiveMatrix BusinessWorks log file (BWLogFileAppender).

To send ATS log messages to a separate file, you must modify the TIBCO ActiveMatrix BusinessWorks log4j property file. Comment out the line containing: log4j.logger.com.arjuna=WARN, tibco_bw_log. Remove the comment from the line containing #log4j.logger.com.arjuna=WARN, tibco_bw_log, ats_log_file.

See Logging for Third-Party Components for more information about the TIBCO ActiveMatrix BusinessWorks log4j file.

Transaction Recovery

XA Transactions can be recovered in the event of a failure. This section details transaction recovery in the supported transaction managers.

TIBCO BusinessWorks XA Transaction Manager

By default, the transaction manager and the recovery manager are started in the same Java VM as TIBCO ActiveMatrix BusinessWorks. Therefore, the transaction recovery manager is started when TIBCO ActiveMatrix BusinessWorks is started, and no additional recovery configuration is necessary.

You may wish to run the recovery manager in a separate Java VM to allow transaction recovery to occur independently of TIBCO ActiveMatrix BusinessWorks. See the TIBCO BusinessWorks XA Transaction Manager documentation for more information about starting the recovery manager in a separate Java VM. No additional configuration in TIBCO ActiveMatrix BusinessWorks is necessary when running in this mode.

If you are using non-TIBCO JDBC drivers (such as Oracle or IBM JDBC drivers), then edit the file <BW_HOME>/tm/1.0/bin/setupenv.bat or <BW_HOME>/tm/1.0/bin/setup_env.sh. Set the variable TIBCO_TM_JDBC_JARS to the name of the non-TIBCO JDBC driver JAR file.

Java Open Transaction Manager (JOTM)

Transaction recovery is not supported by Java Open Transaction Manager (JOTM). Refer to the JOTM documentation for more information.

Arjuna Transaction Service

By default, both the Arjuna Transaction Manager and the Arjuna Transaction Recovery Manager are started in the same Java VM as TIBCO ActiveMatrix BusinessWorks. Therefore, the transaction recovery manager is started when TIBCO ActiveMatrix BusinessWorks is started, and no additional configuration is necessary. In this configuration however, the transaction recovery manager is disabled if TIBCO ActiveMatrix BusinessWorks is stopped or if the Java VM crashes, and transaction recovery only occurs when TIBCO ActiveMatrix BusinessWorks is restarted.

Running the Arjuna Transaction Recovery Manager in a separate Java VM allows transaction recovery to occur independently, regardless of the status of TIBCO ActiveMatrix BusinessWorks. See the ATS documentation for more information about starting the Arjuna Transaction Recovery Manager in a separate Java VM.

After a failure, the ATS ObjectStore may contain the serialized TIBCO ActiveMatrix BusinessWorks Java classes. When running the recovery manager in a separate Java VM, the recovery manager requires references to the TIBCO ActiveMatrix BusinessWorks .jar files to de-serialize the classes. Therefore, when starting the recovery manager in a separate Java VM, verify the following:

•

The classpath for the Arjuna Transaction Recovery Manager must contain the location of the TIBCO ActiveMatrix BusinessWorks .jar files. The following libraries must be included in <ARJUNATS_HOME>\bin\setup-env.bat:

   <BW_HOME>lib\palettes\plugins.jar

   <BW_HOME>lib\engine.jar

   <TRA_HOME>lib\TIBCOxml.jar

   <TRA_HOME>lib\TIBCOrt.jar

   <TRA_HOME>lib\TIBCrypt.jar

   <TRA_HOME>lib\TIBCOjms.jar

   <TPCL_HOME>jdbc\TIbase.jar

   <TPCL_HOME>jdbc\TIutil.jar

   <TPCL_HOME>jdbc\TIoracle.jar

   <TPCL_HOME>jdbc\TIsqlserver.jar

   <TPCL_HOME>jdbc\TIsybase.jar

   <TPCL_HOME>jdbc\TIdb2.jar

   <J2EE_LIB>\jms.jar

   <ORACLE_LIB>\ojdbc14.jar (when using an Oracle database)

•

The ATS property file for the recovery manager must refer to the same ATS ObjectStore that is configured for TIBCO ActiveMatrix BusinessWorks (see Configuring Transaction Managers for a description of configuring the ATS object store).

•

Do not allow more than one Arjuna Transaction Recovery Manager to refer to the same ATS ObjectStore. That is, do not start one recovery manager in the same Java VM as TIBCO ActiveMatrix BusinessWorks, and then start another recovery manager in a different Java VM when both recovery managers are pointing to the same ATS ObjectStore.

•

Recovery may not be possible if the ATS ObjectStore is modified or destroyed. See the ATS documentation for more information.

Refer to the Arjuna Transaction Service documentation for more information about transaction recovery.

When using the Oracle database, the following exception is logged by the ATS recovery manager after invoking the method "getConnection" of the XAConnectionRecovery object:

"2004-08-24 17:20:56,929 [Thread-5] WARN com.arjuna.ats.jta.logging.loggerI18N - [com.arjuna.ats.internal.jta.recovery.xarecovery1] XARecoveryModule.xaRecovery got XA exception javax.transaction.xa.XAException: [tibcosoftwareinc][Oracle JDBC Driver][Oracle]ORA-00942: table or view does not exist, XAException.XAER_RMERR"

This may be caused either by a missing table or by a lack of permissions.

Check that the database user which the recovery manager's connection is using is the same as the one the business logic is using. Also, check that this user has the correct permissions on relevant data dictionary tables and views for the XA system.

PreCreating XA Transactions At Event Sources

BusinessWorks supports including Event Sources such as JMS Queue Receiver, AE Subscriber in a transaction. For the XA Transaction Type, Event Sources can be included in the Transaction Group by selecting the Event Source in the Include In Transaction dropdown list.

The transaction is created when the message arrives at the Event Source.
However, transactions are required to be created before the message arrives at the Event Source when IBM MQ Websphere is used. BusinessWorks enables this feature by providing an option to create transactions at the Event Sources before the message arrives.

Monitoring XA Transactions

TIBCO ActiveMatrix BusinessWorks provides TIBCO Hawk microagent methods for monitoring XA transactions processed by TIBCO XA Transaction Manager or Arjuna Transaction manager. You can use the Hawk console to return a list of transactions that are currently being processed, or you can return statistics for all transactions since the process engine started. The two microagent methods available for transaction monitoring are ListInflightTransactions() and GetTransactionStatus(). See TIBCO Administrator User’s Guide for more information about these microagent methods.

Field	Description
Transaction Manager	An XA Transaction shared configuration resource. See TIBCO ActiveMatrix BusinessWorks Palette Reference for more information about this resource.
Include In Transaction	Certain resources, such as JMS Queue Receiver, Wait for JMS Queue Message, or JMS Topic Subscriber expect acknowledge messages to be sent to the server. Normally, this is done by using a Confirm activity. These resources can also specify an acknowledge mode of "Transactional" that specifies their acknowledgement should be part of a transaction. This field allows you to specify the resource for which you would like to send an acknowledgement message. This message is part of the transaction, if the transaction completes successfully. There is no need for a Confirm activity for the resources specified in this field. Note: Transactional acknowledge mode is not supported for Wait for JMS Topic Message activities.
Include Checkpoint	When this field is checked, an implicit checkpoint is performed after the last activity in the group completes successfully and before the transaction is committed. The deployment configuration must specify a database for storing process engine information and the JDBC Connection used must specify XA as the connection type for this checkpoint to participate in the transaction.
Checkpoint Duplicate Key	When the Include Checkpoints field is checked, you can specify a duplicate key in this field to perform duplicate checking. This is useful if the checkpoint included in the transaction is the first checkpoint in the process definition. If the process engine crashes after the checkpoint, restarted process instances can use the duplicate key to determine if the transaction has already occurred. See Detecting Duplicate Process Instances for more information about specifying duplicate keys.