Distributed multiple resource transactions in Java are usually accomplished by resorting to the Java Transaction API (JTA). One usually delegates the task of distributed transaction coordination to an entity called the Transaction Manager.

The transaction manager is then responsible for coordinating the distributed transaction by interacting with each resource‘s own Resource Manager. Fully fledged enterprise containers include a JTA implementation but what if we need JTA outside an enterprise container, ie. a servlet container like Tomcat?

In this case we must use a 3rd party JTA implementation. In this tutorial we will use Atomikos, a quality JTA implementation which is also available as an open source distribution, along with the Spring framework in order to implement JTA transactions.

This tutorial considers the following environment:

1. Ubuntu 12.04
2. JDK 1.7.0.21
3. Spring 3.2.3
4. Atomikos 3.8.0
5. Tomcat 7.0.35

The following Maven dependencies are required:

<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <spring.version>3.2.3.RELEASE</spring.version>
  <hibernate.version>4.1.9.Final</hibernate.version>
  <atomikos.version>3.8.0</atomikos.version>
</properties>

<dependencies>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <version>${spring.version}</version>
  </dependency>

  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>${spring.version}</version>
  </dependency>

  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-tx</artifactId>
    <version>${spring.version}</version>
  </dependency>

  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-orm</artifactId>
    <version>${spring.version}</version>
  </dependency>

  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>${spring.version}</version>
  </dependency>

  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc</artifactId>
    <version>${spring.version}</version>
  </dependency>

  <dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-entitymanager</artifactId>
    <version>${hibernate.version}</version>
    <exclusions>
      <exclusion>
        <groupId>cglib</groupId>
        <artifactId>cglib</artifactId>
      </exclusion>
      <exclusion>
        <groupId>dom4j</groupId>
        <artifactId>dom4j</artifactId>
      </exclusion>
    </exclusions>
  </dependency>

  <dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.0.1</version>
    <scope>provided</scope>
  </dependency>

  <dependency>
    <groupId>com.atomikos</groupId>
    <artifactId>transactions-jta</artifactId>
    <version>${atomikos.version}</version>
  </dependency>

  <dependency>
    <groupId>com.atomikos</groupId>
    <artifactId>transactions-jdbc</artifactId>
    <version>${atomikos.version}</version>
  </dependency>

  <dependency>
    <groupId>com.atomikos</groupId>
    <artifactId>transactions-hibernate3</artifactId>
    <version>${atomikos.version}</version>
    <exclusions>
      <exclusion>
        <artifactId>hibernate</artifactId>
        <groupId>org.hibernate</groupId>
      </exclusion>
    </exclusions>
  </dependency>

  <dependency>
    <groupId>dom4j</groupId>
    <artifactId>dom4j</artifactId>
    <version>1.6.1</version>
  </dependency>

  <dependency>
    <groupId>log4j</groupId>
    <artifactId>log4j</artifactId>
    <version>1.2.16</version>
  </dependency>

  <dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>5.1.25</version>
  </dependency>

</dependencies>

In this tutorial we will use two datasources each one of them referencing a distinct MySQL database. We could have also included a JMS message queue to participate in the distributed transaction as this is also a very common scenario, but for simplicity we will keep up with the two MySQL datasources:

We will use a couple of tables in this example. Datasource 1 will contain TABLE_ONE and Datasource 2 will contain TABLE_TWO:

Now we define a couple of JPA entities to map the two tables mentioned in the previous section.

package com.byteslounge.spring.tx.entity;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
@Table(name = "TABLE_ONE")
public class TableOne {
  
  @Id
    @Column(name = "TABLE_ONE_ID", nullable = false)
    @GeneratedValue(strategy = GenerationType.AUTO)
  private int tableOneId;
  
  @Column(name = "VALUE", nullable = false)
  private String value;

  public int getTableOneId() {
    return tableOneId;
  }

  public void setTableOneId(int tableOneId) {
    this.tableOneId = tableOneId;
  }

  public String getValue() {
    return value;
  }

  public void setValue(String value) {
    this.value = value;
  }

}

package com.byteslounge.spring.tx.entity;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
@Table(name = "TABLE_TWO")
public class TableTwo {
  
  @Id
    @Column(name = "TABLE_TWO_ID", nullable = false)
    @GeneratedValue(strategy = GenerationType.AUTO)
  private int tableTwoId;
  
  @Column(name = "VALUE", nullable = false)
  private String value;

  public int getTableTwoId() {
    return tableTwoId;
  }

  public void setTableTwoId(int tableTwoId) {
    this.tableTwoId = tableTwoId;
  }

  public String getValue() {
    return value;
  }

  public void setValue(String value) {
    this.value = value;
  }

}

We will also use a couple of Spring services as DAO‘s where each one is used to interact with the respective datasource. Following next are the DAO‘s interfaces and implementations:

package com.byteslounge.spring.tx.dao;

import com.byteslounge.spring.tx.entity.TableOne;

public interface TableOneDao {

  void save(TableOne tableOne);
	
}

package com.byteslounge.spring.tx.dao.impl;

import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;

import org.springframework.stereotype.Service;

import com.byteslounge.spring.tx.dao.TableOneDao;
import com.byteslounge.spring.tx.entity.TableOne;

@Service
public class TableOneDaoImpl implements TableOneDao {

  private EntityManager entityManager;

  @PersistenceContext(unitName="PersistenceUnit1")
  public void setEntityManager(EntityManager entityManager) {
    this.entityManager = entityManager;
  }

  @Override
  public void save(TableOne tableOne) {
    entityManager.persist(tableOne);
  }

}

package com.byteslounge.spring.tx.dao;

import com.byteslounge.spring.tx.entity.TableTwo;

public interface TableTwoDao {

  void save(TableTwo tableTwo) throws Exception;
	
}

package com.byteslounge.spring.tx.dao.impl;

import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;

import org.springframework.stereotype.Service;

import com.byteslounge.spring.tx.dao.TableTwoDao;
import com.byteslounge.spring.tx.entity.TableTwo;

@Service
public class TableTwoDaoImpl implements TableTwoDao {

  private EntityManager entityManager;

  @PersistenceContext(unitName="PersistenceUnit2")
  public void setEntityManager(EntityManager entityManager) {
    this.entityManager = entityManager;
  }

  @Override
  public void save(TableTwo tableTwo) throws Exception {
    entityManager.persist(tableTwo);
    throw new Exception("Force transaction rollback");
  }

}

There are a couple of things to note in this DAO‘s. The first one is that each DAO is associated with a distinct PersistenceUnit(we will see how to configure them later in this tutorial).

The second one is that the save method of TableTwoDaoImpl is explicitly throwing an exception. This exception will be used to force the global transaction to rollback. We will also see this in detail in the following tutorial sections.

Finally we need a service to implement our global container managed transaction. Following next is a possible service interface and implementation:

package com.byteslounge.spring.tx.service;

import com.byteslounge.spring.tx.entity.TableOne;
import com.byteslounge.spring.tx.entity.TableTwo;

public interface TransactionalService {

  void persist(TableOne tableOne, TableTwo tableTwo) throws Exception;
  
}

package com.byteslounge.spring.tx.service.impl;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import com.byteslounge.spring.tx.dao.TableOneDao;
import com.byteslounge.spring.tx.dao.TableTwoDao;
import com.byteslounge.spring.tx.entity.TableOne;
import com.byteslounge.spring.tx.entity.TableTwo;
import com.byteslounge.spring.tx.service.TransactionalService;

@Service
public class TransactionalServiceImpl 
         implements TransactionalService {

  @Autowired
  private TableOneDao tableOneDao;
  
  @Autowired
  private TableTwoDao tableTwoDao;
  
  @Override
  @Transactional(rollbackFor=Exception.class)
  public void persist(TableOne tableOne, TableTwo tableTwo) 
         throws Exception {

    tableOneDao.save(tableOne);
    tableTwoDao.save(tableTwo);

  }

}

Thing to note in this service implementation: Method persist is annotated with @Transactional so the method will be executed in a transactional fashion by the Spring container. This method will call the data persistence methods for both DAO‘s we defined earlier.

Transactional annotation has the rollbackFor attribute defined with Exception.class value. This means that the transaction will rollback if an exception of type Exception occurs inside persist method execution.

You can refine the exception types that cause a transaction rollback but for the simplicity of this example we will keep with Exception.

Now the Persistence Context configuration (persistence.xml):

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0"
  xmlns="http://java.sun.com/xml/ns/persistence" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/persistence 
  http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">

 <persistence-unit name="PersistenceUnit1" transaction-type="JTA">
  <class>com.byteslounge.spring.tx.entity.TableOne</class>
  <properties>
   <property name="hibernate.transaction.manager_lookup_class"
   value="com.atomikos.icatch.jta.hibernate3.TransactionManagerLookup" />
   <property name="hibernate.transaction.factory_class"
   value="org.hibernate.transaction.CMTTransactionFactory" />
  </properties>
 </persistence-unit>
  
 <persistence-unit name="PersistenceUnit2" transaction-type="JTA">
  <class>com.byteslounge.spring.tx.entity.TableTwo</class>
  <properties>
   <property name="hibernate.transaction.manager_lookup_class"
   value="com.atomikos.icatch.jta.hibernate3.TransactionManagerLookup" />
   <property name="hibernate.transaction.factory_class"
   value="org.hibernate.transaction.CMTTransactionFactory" />
  </properties>
 </persistence-unit>
  
</persistence>

Here we configure the Persistence Units we are injecting in the DAO‘s we defined earlier. Note that transaction-type attribute of each persistence unit is defined as JTA.

We also define where Hibernate should look for a Transaction Manager. Since we are using Atomikos we will define it as the Hibernate TransactionManagerLookup provided by Atomikos (we are using Hibernate as JPA implementation).

Now we define the necessary Spring beans and also the Spring container configuration:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:p="http://www.springframework.org/schema/p"
  xmlns:context="http://www.springframework.org/schema/context" 
  xmlns:tx="http://www.springframework.org/schema/tx"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
    http://www.springframework.org/schema/context
    http://www.springframework.org/schema/context/spring-context-3.0.xsd
    http://www.springframework.org/schema/tx
    http://www.springframework.org/schema/tx/spring-tx.xsd">

  <tx:annotation-driven />
  <tx:jta-transaction-manager />

  <context:component-scan 
    base-package="com.byteslounge.spring.tx.dao.impl" />
  <context:component-scan 
    base-package="com.byteslounge.spring.tx.service.impl" />
  <context:component-scan 
    base-package="com.byteslounge.spring.tx.servlet" />

  <bean id="entityManagerFactory1"
class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
    <property name="persistenceUnitName" value="PersistenceUnit1" />
    <property name="dataSource" ref="dataSource1" />
    <property name="jpaVendorAdapter">
      <bean 
      class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter">
        <property name="showSql" value="true" />
        <property name="databasePlatform" 
            value="org.hibernate.dialect.MySQL5InnoDBDialect" />
      </bean>
    </property>
  </bean>

  <bean id="entityManagerFactory2"
class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
    <property name="persistenceUnitName" value="PersistenceUnit2" />
    <property name="dataSource" ref="dataSource2" />
    <property name="jpaVendorAdapter">
      <bean 
      class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter">
        <property name="showSql" value="true" />
        <property name="databasePlatform" 
            value="org.hibernate.dialect.MySQL5InnoDBDialect" />
      </bean>
    </property>
  </bean>

  <bean id="dataSource1" 
    class="com.atomikos.jdbc.AtomikosDataSourceBean"
    init-method="init" destroy-method="close">

    <property name="uniqueResourceName" value="DataSource1" />
    <property name="xaDataSource" ref="dataBase1" />
    <property name="poolSize" value="3" />

  </bean>

  <bean id="dataBase1" 
    class="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"
    lazy-init="true">

    <property name="pinGlobalTxToPhysicalConnection" value="true" />
    <property name="user" value="user1" />
    <property name="password" value="passwd1" />
    <property name="url" value="jdbc:mysql://localhost:3306/DATABASE1" />

  </bean>

  <bean id="dataSource2" 
    class="com.atomikos.jdbc.AtomikosDataSourceBean"

    init-method="init" destroy-method="close">
    <property name="uniqueResourceName" value="DataSource2" />
    <property name="xaDataSource" ref="dataBase2" />
    <property name="poolSize" value="3" />

  </bean>

  <bean id="dataBase2" 
    class="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"

    lazy-init="true">
    <property name="pinGlobalTxToPhysicalConnection" value="true" />
    <property name="user" value="user2" />
    <property name="password" value="passwd2" />
    <property name="url" value="jdbc:mysql://localhost:3306/DATABASE2" />

  </bean>

  <bean id="atomikosTransactionManager"
    class="com.atomikos.icatch.jta.UserTransactionManager"
    init-method="init" destroy-method="close">

    <property name="forceShutdown" value="false" />

  </bean>

  <bean id="atomikosUserTransaction" 
    class="com.atomikos.icatch.jta.J2eeUserTransaction"><propertyname="transactionTimeout"value="300"/></bean><beanid="transactionManager"class="org.springframework.transaction.jta.JtaTransactionManager"depends-on="atomikosTransactionManager,atomikosUserTransaction"><propertyname="transactionManager"ref="atomikosTransactionManager"/><propertyname="userTransaction"ref="atomikosUserTransaction"/><propertyname="allowCustomIsolationLevels"value="true"/></bean></beans>

Things to note in Spring configuration:

We are instructing Spring to use a JTA transaction manager (jta-transaction-manager configuration element).

We define a couple of beans to represent the both database connections (beans dataBase1 and dataBase2). The datasource connections are using com.mysql.jdbc.jdbc2.optional.MysqlXADataSource class.

We are defining two Atomikos datasources (dataSource1 and dataSource2) that will be coupled with the respective database connections we just defined.

We are also defining a couple of Entity Manager factories each one associated with the respective Atomikos datasource and the Persistence Units we defined in the previous section.

Finally we define the Atomikos JTA Transaction Manager and the Atomikos JTA User Transaction that will be both used by The Spring JTA Transaction Manager.

If you need more information on the JTA Transaction Manager and JTA User Transaction roles in a JTA distributed transaction you should search the Internet for additional documentation as there is plenty available.

Now we define a simple servlet to test the configuration:

package com.byteslounge.spring.tx.servlet;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import org.springframework.web.HttpRequestHandler;

import com.byteslounge.spring.tx.entity.TableOne;
import com.byteslounge.spring.tx.entity.TableTwo;
import com.byteslounge.spring.tx.service.TransactionalService;

@Component("testServlet")
public class TestServlet implements HttpRequestHandler {
  
  @Autowired
  private TransactionalService transactionalService;
  
  @Override
  public void handleRequest(
      HttpServletRequest req, 
      HttpServletResponse resp)
         throws ServletException, IOException {
    
    TableOne tableOne = new TableOne();
    tableOne.setValue("value1");
    
    TableTwo tableTwo = new TableTwo();
    tableTwo.setValue("value2");
    
    try {
      transactionalService.persist(tableOne, tableTwo);
    } catch (Exception e) {
      e.printStackTrace();
    }
  
  }
  
}

Note that we are implementing Spring HttpRequestHandler interface so we are able to use Spring dependency injection in the servlet itself, but we will not detail this subject in the current tutorial.

After the servlet execution we will observe that neither of the records are inserted in TABLE_ONE and TABLE_TWO. This is because the second transaction is explicitly throwing an Exception as we configured it in the previous sections and so the global transaction is rollback.

In order to make the transaction to successfully commit we just need to remove the explicit exception throwing in Datasource 2DAO:

package com.byteslounge.spring.tx.dao.impl;

import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;

import org.springframework.stereotype.Service;

import com.byteslounge.spring.tx.dao.TableTwoDao;
import com.byteslounge.spring.tx.entity.TableTwo;

@Service
public class TableTwoDaoImpl implements TableTwoDao {

  private EntityManager entityManager;

  @PersistenceContext(unitName="PersistenceUnit2")
  public void setEntityManager(EntityManager entityManager) {
    this.entityManager = entityManager;
  }

  @Override
  public void save(TableTwo tableTwo) throws Exception {
    // Exception throwing is removed
    entityManager.persist(tableTwo);
  }

}

You may find the complete example source code as a downloadable resource at the end of this page. The downloadable sample is explicitly throwing the exception so you may observe the behaviour of global transaction rollback. Change it in order to suit your needs.