Using Z2 with a Transaction Manager

This sample demonstrates how to use Z2 with the Atomikos transaction manager. There is another sample that shows how to use Z2 with a Spring configured transaction manager. See sample-jta-spring. In contrast to that, this sample is less sophisticated but probably better suited to understand the underlying mechanics.

The Wiki page How_to_TransactionManager explains the general principles behind transaction handling in Z2.

This sample is stored in z2-samples.jta-plain. It implements exactly the same scenario as Sample-hibernate-basic with the exception of not using the built-in JTA implementation.


Z2 has the following Java Version requirements

Z2 Version Min. Java version required Max Java version supported
2.1 - 2.3.1 Java 6 Java 7
2.4 - master Java 8 Java 8

Note: Most samples suggest to use the master branch. You may choose another version branch (please check the respective repository).
Make sure you have a corresponding Java Development Kit (JDK) or Java Runtime Environment (JRE) installed. If in doubt, go to Download Java SE.

Note: Running v2.1-v2.3.1 on Java 8 is supported by specifying

(or 6, if that is your desired compilation language level) in <home>/run/bin/ By this the Java compiler version detection does not fall back to a lower level.

You need to run Java DB as network server on localhost. This is explained next.

The application will create a database "z2-samples"

Running a Java DB Network Server

In samples we use the Java DB, i.e. the SQL database implementation that comes with the Java SE Development Kit (JDK) by Oracle (except for Mac OS in which case you have to use Apache Derby). Java DB is the same as the Apache Derby DB - see also the installation how-to.

The instructions below apply to both, there is only a difference in the installation path.

For general information on Java DB go to

To run the Java DB in server mode, which is what we want to do, run

mkdir derby
cd derby
java -jar $JAVA_HOME/db/lib/derbyrun.jar server start

assuming you want to run it in the folder derby. At a second time you can omit the "mkdir" command of course. The environment variable JAVA_HOME is expected to point to your JDK installation folder. When you installed Apache Derby and followed the instructions mentioned above, you have to replace $JAVA_HOME by $DERBY_HOME.

On Windows run

mkdir derby
cd derby
java -jar "%JAVA_HOME%\db\lib\derbyrun.jar" server start

In order to interactively query Java DB, we recommend to use the Data Source Explorer view in Eclipse. But any SQL client that can make use of JDBC drivers should be fine. The driver for Java DB can be found (at the time of this writing) in $JAVA_HOME/db/lib/derbyclient.jar (and similarly on Windows).

Note: If you have problems running Derby due to Security Exceptions, it may be necessary to update your security profile as described in (and please make sure you have a good JAVA_HOME and PATH setting).

Alternative: Using the DB-Worker Node Add-on (no separate RDBMS installation required)

you can also use the DB Worker Node Add-on which runs Apache Derby RDBM as a regular z2 worker process, so you don't need to install any extra database software.

How to augment the samples to use the DB Worker node?

You have to add the DB Worker Node Add-on to your samples environment and tell the server to start the DB worker node beside the web worker.
For this you can use the two files attached to this page:

  • - points to the z2 component repository containing the DB Worker Node Add-on
  • - a slightly changed home layout that launches the DB worker in addition to the web worker

Just download these two files and put them under .../install/z2-samples.XYZ/environment/ - where z2.samples.XYZ must be replaced by the concrete sample name like z2-samples.spring-hibernate

Running the sample

This sample is run as explained in How to run a sample. The 5 minutes version:

mkdir install
cd install 
git clone -b master
git clone -b master

# on Linux / Mac OS:
cd z2-base.core/run/bin

# on Windows:
cd z2-base.core\run\bin


When everything is up, go to http://localhost:8080/jta-plain. You see something like this:

And indeed, the implemented function is rather obvious: Manage a table of strings - called Thingies in the sample.

Now to the point...

The idea behind this sample is to provide a template for transaction manager integration. Note that before you integrate with a complete transaction management system, you should be sure that you need it. Distributed transactions come at a price in terms of complexity and overhead of local transaction logs. If you do not have multiple data sources, or if those have no strong inherent consistency requirement you may well be better off without a full-blown, XA capable transaction manager. Please also see How to transaction management.

Detailed explanation

The sample has four modules:

  • com.atomikos: This module holds the Atomikos Transaction Essentials libraries - the actual transaction manager implementation (via the mvn fragment mvnFragment ntry/com.atomikos/
  • com.zfabrik.samples.jta-plain: This module implements supporting functions for the actual applications.
  • com.zfabrik.samples.jta-plain.domain: The domain definition module. This contains the JPA entities and a "Thingy Repository" implementation.
  • com.zfabrik.samples.jta-plain.web: The simple web application that lists the database content and allows to add and delete thingies.

In order to make Atomikos usable, it's transaction manager and user transaction implementations have to be configured and instantiated. All of that is done in com.zfabrik.samples.jta-plain in the form of Z2 components exposed for re-use by other modules. Similarly the Atomikos XA Data Source implementation is made available from this module (Note: You cannot -for all practical matters - separate data source implementations from the transaction management implementations).

Unlike Sample-jta-spring, the starting point for integrations with the transaction management system - although done only once - are a little more distributed:

In order to simplify transaction manager access from various places, we use a utility class Transactions. This class uses components in com.zfabrik.samples.jta-plain and effectively de-couples the JTA implementation from its access points. This class is used for

  • Jetty Web Container integration:

In order to provide user transaction access via the standard JNDI name java:comp/UserTransaction (although not strictly needed in the example), we adapted jetty.xml accordingly. Check the lines starting with

<New id="tx" class="">...
  • Hibernate integration:

Hibernate accesses the transaction manager via our custom AtomikosJTAPlatform (see also as declared in the persistence unit

plain_thingies.png (29.6 KB) Henning Blohm, 15.09.2012 10:44