z2-Environment

h1. Using Z2 with a Transaction Manager

(Work in progress)

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":http://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-jta-plain.

h2. Pre-Requisites

This sample assumes the presence of a MySQL database system on localhost with a database called "z_tx_tests" for which a user "tx" with password "tx" has full permissions. If you have a running MySQL server these SQL commands do the trick:

<pre><code class="SQL">

create database z_tx_tests;

grant all on z_tx_tests.* to tx@localhost identified by 'tx';

</code></pre>

h2. Running the sample

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

<pre><code class="ruby">

mkdir install

cd install 

git clone -b master http://git.z2-environment.net/z2-base.core

git clone -b master http://git.z2-environment.net/z2-samples.jta-plain

# on Linux / Mac OS:

cd z2-base.core/run/bin

./gui.sh

# on Windows:

cd z2-base.core\run\bin

gui.bat

</code></pre>

h2. Verifying

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

!plain_thingies.png!

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

h2. 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]].

h2. Detailed explanation

The sample has four modules:

* *com.atomikos*: This module holds the "Atomikos Transaction Essentials":http://www.atomikos.com/Main/TransactionsEssentials libraries - the actual transaction manager implementation* 

* *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.

Let's start by looking at the supporting functions. Note that the Spring Framework as used in the other sample [[Sample.jta-spring]] implements these supportive functions.

We only care about database transactions here. The typical issues to be tackled when working with database connections are

h4. Provide control over transaction scopes

As we use the Java Transaction API ("JTA":http://de.wikipedia.org/wiki/Java_Transaction_API) the "UserTransaction":http://docs.oracle.com/javaee/6/api/javax/transaction/UserTransaction.html interface is what matters. Atomikos implements it, but it is in our responsibility 

h4. One connection per transaction scope and datasource

h4. One entity manager per transaction scope and persistence unit

INTEGRATION POINTS:

* Jetty Transaction (see e.g. http://docs.codehaus.org/display/JETTY/JNDI)