Project

General

Profile

How to Transaction Management » History » Version 13

Henning Blohm, 17.09.2012 15:03

1 10 Henning Blohm
h1. Transaction management in Z2
2 3 Henning Blohm
3 11 Henning Blohm
(work in progress)
4
5 12 Henning Blohm
This page provides some hints and pointers on how to implement transaction management for modular applications on Z2. There are a few utilities provided with Z2 that may help you implement transaction handling for the simple cases, and this site provides examples that show how to address the more complicated cases.
6
7
Everything below is describing use and enabling of a Java Transaction API ("JTA":http://de.wikipedia.org/wiki/Java_Transaction_API) based approach to transaction management. 
8
9
Note that there is nothing in Z2 that prevents you from using a previously implemented Web application-local based transaction management. The information on this page is most useful, if you have a modular application that requires transaction management also on a service level.
10
11
The following aspects will be discussed:
12
13
* The built-in, non-XA JTA implementation of Z2
14
* Controlling transactions in code
15
* Using Datasource components
16
* Using Hibernate JPA
17
* Using a full-blown transaction manager
18
* Integration with Jetty
19
* Integration with Spring
20
21
h2. The built-in, non-XA JTA implementation of Z2 (com.zfabrik.jta)
22
23
The "z2-base.base":http://redmine.z2-environment.net/projects/z2-base/repository/base repository contains the JTA 1.1 API and an implementation of it in the module *com.zfabrik.jta*. 
24
25
*Note*: This is not an XA-capable transaction manager. This implementation provides no atomic transaction control for more than one transactional resource!
26
27
But, this implementation is still most useful, if you do not need distributed transactions (which is preferable in most cases) and still want to benefit from the JTA API as an integration point.
28
29
Technically the implementation relies on Z2's _Unit of Work_ abstraction (see "Unit of Work and transaction management":http://www.z2-environment.eu/v21doc#Unit%20of%20Work%20and%20transaction%20management). As long as all interactions with an application are issued from a Web application this is completely transparent. When invoking code from other entry points, e.g. from an embedded scheduling service for example, this has an impact that will be discussed below.
30
31
The "TransactionManager":http://docs.oracle.com/javaee/6/api/javax/transaction/TransactionManager.html interface, as well as the "UserTransaction":http://docs.oracle.com/javaee/6/api/javax/transaction/UserTransaction.html interface are available from the component *com.zfabrik.jta/userTransaction* and can be looked up via the Z2 core API
32
33
<pre><code class="java">IComponentsLookup.INSTANCE.lookup("com.zfabrik.jta/userTransaction",TransactionManager.class)</code></pre>
34
35
or via JNDI as
36
37
<pre><code class="java">new InitialContext().lookup("components:com.zfabrik.jta/userTransaction?type=javax.transaction.TransactionManager")</code></pre>
38
39
and similarly for the UserTransaction interface.
40
41
This simple approach to JTA has been used in the samples [[Sample-hibernate-basic-TBD]] and [[Sample-spring-hibernate-TBD]].
42
43
h2. Controlling transactions in code
44
45
Now that you have a JTA implementation you need to indicate where transactions start and end. The most basic (and most understandable) approach to that is to use the UserTransaction interface. Typically in a flow like this:
46
47
<pre><code class="java">
48
UserTransaction ut = (UserTransaction) new InitialContext().lookup( JNDI_NAME );
49
ut.begin();
50
try {
51
  // do some work
52
} catch (Exception e) {
53
  logger.log(Level.WARNING,"Error at transaction boundary. Setting transaction to rollbackonly",e);
54
  ut.setRollbackOnly();
55
  throw e;
56
} finally {
57
  if (ut.getStatus()==Status.STATUS_ACTIVE) {
58
    ut.commit();
59
  } else {
60
    ut.rollback();
61
  }
62
}
63
</code></pre>
64
65
The constant *JNDI_NAME* is intentionally left undefined here. If you use *com.zfabrik.jta* you may use the name specified above. If the code above is part of a Servlet Filter that is supposed to begin and end transactions on the boundaries of a Web request, you can use the standard name "java:comp/UserTransaction" given you integrated the transaction management with Jetty (see below).
66
67
Now that we looked at it, fortunately you do not need to implement this yourself. Here are some alternatives:
68
69
* Use "TransactionUtil":http://redmine.z2-environment.net/projects/z2-base/repository/base/revisions/master/entry/com.zfabrik.jta/java/src.api/com/zfabrik/tx/TransactionUtil.java from *com.zfabrik.jta* that implements just the flow above.
70
* Use Spring's transaction management support including annotation based transaction demarcation, as for example in [[Sample-spring-hibernate-TBD]] and [[Sample-jta-spring]] (see also [[How to Spring]]).
71
* Use any of the many "Transaction Filter" implementations out there.
72
73
h2. Using DataSource components
74
75
A JDBC data source wraps JDBC connections, i.e. actual database connections, for re-use along the control flow. 
76
77
When accessing the same database multiple times within one transaction, you want to make sure you re-use the same (underlying) JDBC connection. That is, you may (typically) not have more than one (underlying) JDBC connection to the very same database that share the same (non-distributed) transaction. Hence the typical implementation associates a JDBC connection to a database with the transaction that is associated with the current thread of execution. Obviously there is a strong tie between the management of database connections and the transaction management system. JDBC data sources provide the accessor interface to database connections. You may hold of to a data source and ask it for a connection when needed, but you should not hold on to the actual connection object between invocations of your service interface. 
78
79
Z2 offers a built-in DataSource component type. This is useful, if you use *com.zfabrik.jta*. If you use another transaction management system, you should most likely use another data source implementation. See for example [[Sample-jta-plain]].
80
81
When using the built-in data source, you can look up the "DataSource":http://docs.oracle.com/javase/6/docs/api/javax/sql/DataSource.html interface via a component lookup, e.g. via JNDI like this:
82
83
<pre><code class="java">(DataSource) new InitialContext().lookup(COMPONENT_NAME?type=javax.sql.DataSource)</code></pre>
84
85
where *COMPONENT_NAME* has to be substituted by the real name of the data source component.
86
87
The built-in data sources have been used for example in [[Sample-hibernate-basic-TBD]] and [[Sample-spring-hibernate-TBD]].
88
89
90
h2. Using Hibernate and JPA
91
92 13 Henning Blohm
Now you have a JTA implementation in place as well as data sources defined, assuming you want to use the "Java Persistence API":http://de.wikipedia.org/wiki/Java_Persistence_API you buy into yet another layer that needs to be integrated with the transaction management system. 
93
94
In JPA, the equivalent of a data base connection is the "EntityManager":http://docs.oracle.com/javaee/6/api/javax/persistence/EntityManager.html interface. And as with connections and data sources, you will want to reuse the entity manager instance across invocations within one transaction. An entity manager is created from an "EntityManagerFactory":http://docs.oracle.com/javaee/6/api/javax/persistence/EntityManagerFactory.html given a definition of a _Persistence Unit_. We cannot go into all the details here. 
95
96
In Java EE environments, you may delegate the creation of entity managers to the container and have it _injected_ into your code using a corresponding annotation. The same comfort (and beyond that) can be achieved in Z2 even across modules using the Spring framework (see for example [[Sample-spring-hibernate-TBD]] and [[Sample-jta-spring]]). 
97
98
The underlying implementation however is always about associating an entity manager with the ongoing transaction. If you do not want to use Spring or want to fully understand the principle mechanics, you may use the "EntityManagerUtil":http://redmine.z2-environment.net/projects/z2-base/repository/base/revisions/master/entry/org.hibernate/java/src.api/com/zfabrik/hibernate/EntityManagerUtil.java of the module *org.hibernate* in *z2-base.base". This is how it is done in [[Sample-hibernate-basic]].
99
100
To connect a persistence unit (and hence the entity manager factory) with the transaction management and the data source to use, you add corresponding information to the file "META-INF/persistence.xml":http://redmine.z2-environment.net/projects/z2-samples/repository/revisions/master/entry/com.zfabrik.samples.hibernate-basic.domain/java/src.impl/META-INF/persistence.xml of your domain module. For example, the one in [[Sample-hibernate-basic]] looks like this:
101
102
<pre><code class="xml">
103
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
104
   <persistence-unit name="thingies" transaction-type="JTA">
105
      <provider>org.hibernate.ejb.HibernatePersistence</provider>
106
      <jta-data-source>components:com.zfabrik.samples.hibernate-basic.domain/DB</jta-data-source>
107
      <class>com.zfabrik.samples.hibernate_basic.thingies.Thingy</class>
108
      <exclude-unlisted-classes>true</exclude-unlisted-classes>
109
      <properties>
110
         <property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect" />
111
         <property name="hibernate.hbm2ddl.auto" value="update" />
112
         <property name="hibernate.jdbc.batch_size" value="10" />
113
         <property name="hibernate.cache.use_second_level_cache" value="false" />
114
         <property name="hibernate.transaction.manager_lookup_class" value="com.zfabrik.hibernate.TransactionManagerLookup" />
115
       </properties>
116
  </persistence-unit>
117
</persistence>
118
</code></pre>
119
120
The noteworthy pieces are 
121
122
# The <jta-data-source/> definition that uses a DataSource JNDI name as discussed above.
123
# The <property name="hibernate.transaction.manager_lookup_class"/> declaration
124
125
The latter is required for Hibernate to find the transaction manager instance. Unfortunately Hibernate does not support a JNDI name for that. That's why the module *org.hibernate* provides an implementation you can use (it's really simple. See "TransactionManagerLookup":http://redmine.z2-environment.net/projects/z2-base/repository/base/revisions/master/entry/org.hibernate/java/src.api/com/zfabrik/hibernate/TransactionManagerLookup.java).
126
127
When not using *com.zfabrik.jta*, the value to specify differ of course. See also [[Samples-jta-plain]].
128
129
130
There is various ways 
131 12 Henning Blohm
132
133
134
 What data source
135
136
 
137
138
139
140
141
142
143
144
145
If you have implemented transaction management locally to a Web application already using Hibernate Sessions or the simple transaction management provided by the Spring framework and you do not intent to have other entry points to your application scenario you may skip this page.
146
147
148
(work in progress)
149
150
151
152 11 Henning Blohm
Alternatives - mini JTA, full JTA.
153
Integration points: Jetty, Hibernate, Spring
154
155
Explain transaction util.
156
157
------------
158
159
160 3 Henning Blohm
This Wiki is about how to integrate a full-blown transaction manager into Z2. We only consider Atomikos for now, hoping other TMs can be used similarly.
161
162 4 Henning Blohm
Note that the z2-base.base repository contains the JTA 1.1 API and an implementation of it in the module *com.zfabrik.jta*. That is however not a real, full-featured transaction manager - rather just a pseudo-distributed transaction management implementation. There is no 2-phase-commit handling. 
163
164
It is still extremely useful for 90% case where global, distributed transactions are unnecessary overkill. 
165 3 Henning Blohm
166
At times however, you may require a real TM and even if you dont and want to use Atomikos with non-XA data sources, in which case it behaves similarly to *com.zfabrik.jta*, here is how it's done.
167
168
There are two samples related to this page:
169
170 8 Henning Blohm
* *z2-samples.jta-plain*: A sample scenario with just z2-base and Atomikos and no further trickery. This samples explains best what is needed to get going. See also [[Sample_jta_plain]].
171 7 Henning Blohm
* *z2-samples.jta-spring*: A sample scenario built on z2-base, z2-addons.spring, and Atomikos. This is the more advanced, Spring-minded case. The underlying mechanics may be harder to grasp though. See also [[samples_jta_spring]].
172 3 Henning Blohm
173
Please consult [[How_to_Run_a_Sample]] on how to run these samples.
174 6 Henning Blohm
175
h2. References
176
177
* [[How_to_Run_a_Sample]]
178
* [[How_to_Spring]]