In WSO2 ESB, JMS transactions only work with either the Callout mediator or the Call mediator in blocking mode.

The JMS transport shipped with WSO2 ESB supports both local and distributed JMS transactions. You can use local transactions to group messages received in a JMS queue. Local transactions are not supported for messages sent to a JMS queue.

JMS local transactions

A local transaction represents a unit of work on a single connection to a data source managed by a resource manager. In JMS, you can use the JMS API to get a transacted session and to call methods for commit or roll back for the relevant transaction objects. This is managed internally by a resource manager. There is no external transaction manager involved in the coordination of such transactions.

Let's explore a a sample scenario that demonstrates how to handle a transaction using JMS in a situation where the back-end service is unreachable.

Sample scenario

A message is read from a JMS queue and is processed by a back-end service. In the successful scenario, the transaction will be committed and the request will be sent to the back end service. In the failure scenario, while executing a sequence, a failure occurs and the ESB receives a fault. This cause the JMS transaction to roll back.

The sample scenario can be depicted as follows:

Prerequisites

Windows, Linux or Solaris operating systems with WSO2 ESB installed. For instructions on downloading and installingWSO2 ESB, see Getting Started with WSO2 ESB.

Configuring the sample scenario

Configure the JMS local transaction by defining the following parameter in the <ESB HOME>/repository/conf/axis2/axis2.xml file. By default the session is not transacted. In order to make it transacted, set the parameter to true.

<parameter name="transport.jms.SessionTransacted">true</parameter>

Once done, the JMS listener configuration for WSO2 MB in the axis2.xml file should be as follows:

According to the above configuration, a message will be read from the JMS queue and will be sent to the SimpleStockQuoteService running on the Axis2 back-end server. If a failure occurs, the transaction will roll back.

In the above configuration, the following property is set to true in the fault handler, in order to roll back the transaction when a failure occurs.

Testing the sample scenario

In order to simulate the successful scenario, the message should mediate successfully.

When the message mediates successfully, the output on the Axis2 server start-up console will be as follows:

The ESB debug log will display an INFO message as follows, indicating that the transaction is committed.

Failure Scenario

In order to simulate the failure scenario, you need to stop the sample Axis2 Server and execute the JMS client once again. In this scenario, the ESB debug log will display an INFO message as follows, indicating that the transaction is rolled back.

JMS distributed transactions

The WSO2 ESB also supports distributed JMS transactions. You can use the JMS transport with more than one distributed resource, for example, two remote database servers. An external transaction manager coordinates the transaction. Designing and using JMS distributed transactions is more complex than using local JMS transactions.

The transaction mediator can be used to mark a distributed transaction, which involves a distributed transaction that spans through multiple resources. The transaction manager is the primary component of the distributed transaction support infrastructure. However, the JDBC driver and the application server where you deploy the applications should have the following two characteristics:

The driver should implement the JDBC 2.0 API (including the optional package interfaces XADataSource and XAConnection) or higher, and the JTA interface XAResource.

The application server should provide a Datasource class that is implemented to interact with the distributed transaction infrastructure and a connection pooling model for performance improvements.

When JMS transactions are in place, local transactions are managed by the JMS provider itself, whereas the distributed JMS transactions are managed by the XAResource enabled transaction manager in the Java EE application server.

Check if your application server provides a XAConnectionFactory when you look for the ConnectionFactory.