This documentation is for WSO2 ESB version 4.5.1. View documentation for the latest release.

Skip to end of metadata
Go to start of metadata

A transaction is a set of operations executed as a single unit. It also can be defined as an agreement, which is carried out between separate entities or objects. A transaction can be considered as indivisible or atomic when it has the characteristic of either being completed in its entirety or not at all. During the event of a failure for a transaction update, atomic transaction type guarantees transaction integrity such that any partial updates are rolled back automatically.

Transactions have many different forms, namely Financial transactions, Database transactions, etc. In the ESB point of view, there are two types of transactions:

Distributed Transaction

A distributed transaction is a transaction that updates data on two or more networked computer systems. It extends the benefits of transactions to applications that must update distributed data. Implementing robust distributed applications is difficult because these applications are subject to multiple failures, including failure of the client, the server, and the network connection between the client and server. For distributed transactions, each computer has a local transaction manager. When a transaction works at multiple computers, the transaction managers interact with other transaction managers via either a superior or subordinate relationship. These relationships are relevant only for a particular transaction.

Java Message Service(JMS) Transactions

In addition to the distributed transactions, WSO2 ESB also has the support for JMS transactions. The JMS transport which ships with WSO2 ESB has the support for both local and distributed transactions.

JMS Local Transaction

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

JMS Local Transaction Configuration

To start a local JMS transaction, define the following property in JMS transport Listner/Sender in axis2.xml (see more information about transports in WSO2 Carbon Transports and Transports).

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

By default, the session is not transacted and if you want to use JMS local transaction, set the above parameter to true. And you need to set the following property in synapse fault handler to rollback the transaction in case of a failure.

<property name="SET_ROLLBACK_ONLY" value="true" scope="axis2"/>

There is an example of JMS local transaction in the article.

JMS Distributed Transaction

WSO2 ESB also has the support for distributed JMS transaction. You can use JMS transport with more than one distributed resources (for example a JMS queue and a remote database server).

An external transaction manager manages the coordination of the transaction. Designing and using JMS distributed transactions is more complex than using local JMS transactions.

The transaction manager is the primary component of the distributed transaction support infrastructure, however the JDBC driver (the resource adapter) and the application server (in which 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 J2EE application server.


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

If you need an in-depth knowledge in transactions (distributed transactions, JMS local and distributed transaction etc.), go here.

Transaction Mediator

A new synapse mediator (Transaction Mediator) has been added to support the distributed transactions using Java transaction API(JTA). JTA allows applications to perform a distributed transaction that is, transactions that access and update data on two or more networked computer resources (an example would be to have two databases or a database and a message queue such as JMS). This mediator can be used to perform a distributed transaction. The synapse configuration has been extended to add explicit transaction markers. What this means is you can use the synapse configuration language to define the start, end etc. of your transaction. It is the responsibility of the user to define when to start, commit or rollback the transaction. For example, you can mark the start of a transaction at the start of a database commit and end of the transaction at the end of the database commit and you can mark rollback transaction if a failure occurs.

Transaction Mediator Configuration
<transaction action="new|use-existing-or-new|fault-if-no-tx|commit|rollback|suspend|resume"/>

The action attribute has the following meanings:




Creates a new JTA transaction. Generates a fault if a transaction already exist.


Creates a new JTA transaction. Does nothing if a transaction exists.


Generates a fault if no transaction exist. Does nothing if a transaction exists.


Commits transaction. Generates a fault if no transaction exists.


Rollbacks transaction. Generates a fault if no transaction exists.


Suspends transaction. Generates a fault if no transaction exists.


Resumes transaction. Generates a fault if no transaction exists.



  • No labels