Project

General

Profile

Sample-jta-plain » History » Version 17

Henning Blohm, 10.09.2015 15:27

1 3 Henning Blohm
h1. Using Z2 with a Transaction Manager
2 1 Henning Blohm
3 2 Henning Blohm
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.
4 1 Henning Blohm
5
The Wiki page [[How_to_TransactionManager]] explains the general principles behind transaction handling in Z2.
6
7 11 Henning Blohm
This sample is stored in "z2-samples.jta-plain":http://redmine.z2-environment.net/projects/z2-samples/repository/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.
8 2 Henning Blohm
9 12 Henning Blohm
h2. Prerequisites
10 2 Henning Blohm
11 17 Henning Blohm
You need is a JDK 6 or JDK 7 distribution as described in [[Step_2_-_Install_and_run_in_5_minutes]].
12
13
*NOTE:* All versions less than 3 will not run with Java 8. You need to use Java 7 instead!
14
15 12 Henning Blohm
You need to run Java DB as network server on localhost. This is explained next.
16 2 Henning Blohm
17 12 Henning Blohm
The application will create a database "z2-samples"
18
19
{{include(How to run Java db)}}
20 2 Henning Blohm
21
h2. Running the sample
22
23
This sample is run as explained in [[How to run a sample]]. The 5 minutes version:
24
25
<pre><code class="ruby">
26
mkdir install
27
cd install 
28
git clone -b master http://git.z2-environment.net/z2-base.core
29
git clone -b master http://git.z2-environment.net/z2-samples.jta-plain
30
31
# on Linux / Mac OS:
32
cd z2-base.core/run/bin
33
./gui.sh
34
35
# on Windows:
36
cd z2-base.core\run\bin
37
gui.bat
38 1 Henning Blohm
</code></pre>
39 3 Henning Blohm
40
h2. Verifying
41
42 14 Henning Blohm
When everything is up, go to http://localhost:8080/jta-plain. You see something like this: 
43 3 Henning Blohm
44
!plain_thingies.png!
45
46 5 Henning Blohm
And indeed, the implemented function is rather obvious: Manage a table of strings - called Thingies in the sample.
47 3 Henning Blohm
48
h2. Now to the point...
49 4 Henning Blohm
50 1 Henning Blohm
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]].
51 5 Henning Blohm
52 6 Henning Blohm
h2. Detailed explanation
53 5 Henning Blohm
54
The sample has four modules:
55
56 15 Henning Blohm
* *com.atomikos*: This module holds the "Atomikos Transaction Essentials":http://www.atomikos.com/Main/TransactionsEssentials libraries - the actual transaction manager implementation (via the mvn fragment "mvnFragment":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-jta-plain/revisions/master/ee ntry/com.atomikos/mvnFragment.properties).
57 7 Henning Blohm
* *com.zfabrik.samples.jta-plain*: This module implements supporting functions for the actual applications.
58
* *com.zfabrik.samples.jta-plain.domain*: The domain definition module. This contains the JPA entities and a "Thingy Repository" implementation.
59 1 Henning Blohm
* *com.zfabrik.samples.jta-plain.web*: The simple web application that lists the database content and allows to add and delete thingies.
60
61 16 Henning Blohm
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).
62
63 1 Henning Blohm
Unlike [[Sample-jta-spring]], the starting point for integrations with the transaction management system - although done only once - are a little more _distributed_:
64
65 16 Henning Blohm
In order to simplify transaction manager access from various places, we use a utility class "Transactions":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-jta-plain/revisions/master/entry/environment/java/src.api/com/zfabrik/samples/jta_plain/jta/Transactions.java. 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
66 15 Henning Blohm
67 16 Henning Blohm
* *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":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-jta-plain/revisions/master/entry/environment/webServer/jetty.xml accordingly (check @<New id="tx" class="org.eclipse.jetty.plus.jndi.Transaction">...@).
68
* *Hibernate integration:* Hibernate accesses the transaction manager via our custom "AtomikosJTAPlatform":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-jta-plain/revisions/master/entry/com.zfabrik.samples.jta-plain/java/src.api/com/zfabrik/samples/jta_plain/hibernate/AtomikosJTAPlatform.java (see also http://stackoverflow.com/questions/20681245/how-to-use-atomikos-transaction-essentials-with-hibernate-4-3) as declared in the "persistence unit":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-jta-plain/revisions/master/entry/com.zfabrik.samples.jta-plain.domain/java/src.impl/META-INF/persistence.xml