/
architecture.xml
291 lines (250 loc) · 13.2 KB
/
architecture.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2010, Red Hat Inc or third-party contributors as
~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are
~ distributed under license by Red Hat Inc.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
~ Lesser General Public License, as published by the Free Software Foundation.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
~ for more details.
~
~ You should have received a copy of the GNU Lesser General Public License
~ along with this distribution; if not, write to:
~ Free Software Foundation, Inc.
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="architecture">
<title>Architecture</title>
<section>
<title>Definitions</title>
<para>JPA 2 is part of the Java EE 6.0 platform. Persistence in JPA is
available in containers like EJB 3 or the more modern CDI (Java Context
and Dependency Injection), as well as in standalone Java SE applications
that execute outside of a particular container. The following programming
interfaces and artifacts are available in both environments.</para>
<variablelist spacing="compact">
<varlistentry>
<term><literal>EntityManagerFactory</literal></term>
<listitem>
<para>An entity manager factory provides entity manager instances,
all instances are configured to connect to the same database, to use
the same default settings as defined by the particular
implementation, etc. You can prepare several entity manager
factories to access several data stores. This interface is similar
to the <literal>SessionFactory</literal> in native Hibernate.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>EntityManager</literal></term>
<listitem>
<para>The <literal>EntityManager</literal> API is used to access a
database in a particular unit of work. It is used to create and
remove persistent entity instances, to find entities by their
primary key identity, and to query over all entities. This interface
is similar to the <literal>Session</literal> in Hibernate.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Persistence context</term>
<listitem>
<para>A persistence context is a set of entity instances in which
for any persistent entity identity there is a unique entity
instance. Within the persistence context, the entity instances and
their lifecycle is managed by a particular entity manager. The scope
of this context can either be the transaction, or an extended unit
of work.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Persistence unit</term>
<listitem>
<para>The set of entity types that can be managed by a given entity
manager is defined by a persistence unit. A persistence unit defines
the set of all classes that are related or grouped by the
application, and which must be collocated in their mapping to a
single data store.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Container-managed entity manager</term>
<listitem>
<para>An Entity Manager whose lifecycle is managed by the
container</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Application-managed entity manager</term>
<listitem>
<para>An Entity Manager whose lifecycle is managed by the
application.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>JTA entity manager</term>
<listitem>
<para>Entity manager involved in a JTA transaction</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Resource-local entity manager</term>
<listitem>
<para>Entity manager using a resource transaction (not a JTA
transaction).</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>In container environment (eg. EJB 3)</title>
<section>
<title>Container-managed entity manager</title>
<para>The most common and widely used entity manager in a Java EE
environment is the container-managed entity manager. In this mode, the
container is responsible for the opening and closing of the entity
manager (this is transparent to the application). It is also responsible
for transaction boundaries. A container-managed entity manager is
obtained in an application through dependency injection or through JNDI
lookup, A container-managed entity manger requires the use of a JTA
transaction.</para>
</section>
<section>
<title>Application-managed entity manager</title>
<para>An application-managed entity manager allows you to control the
entity manager in application code. This entity manager is retrieved
through the <literal>EntityManagerFactory</literal> API. An application
managed entity manager can be either involved in the current JTA
transaction (a JTA entity manager), or the transaction may be controlled
through the <literal>EntityTransaction</literal> API (a resource-local
entity manager). The resource-local entity manager transaction maps to a
direct resource transaction (i. e. in Hibernate's case a JDBC
transaction). The entity manager type (JTA or resource-local) is defined
at configuration time, when setting up the entity manager
factory.</para>
</section>
<section id="architecture-ejb-persistctxscope">
<title>Persistence context scope</title>
<para>An entity manager is the API to interact with the persistence
context. Two common strategies can be used: binding the persistence
context to the transaction boundaries, or keeping the persistence
context available across several transactions.</para>
<para>The most common case is to bind the persistence context scope to
the current transaction scope. This is only doable when JTA transactions
are used: the persistence context is associated with the JTA transaction
life cycle. When an entity manager is invoked, the persistence context
is also opened, if there is no persistence context associated with the
current JTA transaction. Otherwise, the associated persistence context
is used. The persistence context ends when the JTA transaction
completes. This means that during the JTA transaction, an application
will be able to work on managed entities of the same persistence
context. In other words, you don't have to pass the entity manager's
persistence context across your managed beans (CDI) or EJBs method
calls, but simply use dependency injection or lookup whenever you need
an entity manager.</para>
<para>You can also use an extended persistence context. This can be
combined with stateful session beans, if you use a container-managed
entity manager: the persistence context is created when an entity
manager is retrieved from dependency injection or JNDI lookup , and is
kept until the container closes it after the completion of the
<literal>Remove</literal> stateful session bean method. This is a
perfect mechanism for implementing a "long" unit of work pattern. For
example, if you have to deal with multiple user interaction cycles as a
single unit of work (e.g. a wizard dialog that has to be fully
completed), you usually model this as a unit of work from the point of
view of the application user, and implement it using an extended
persistence context. Please refer to the Hibernate reference manual or
the book Hibernate In Action for more information about this pattern.
</para>
<para>JBoss Seam 3 is built on top of CDI and has at it's core concept
the notion of conversation and unit of work. For an application-managed
entity manager the persistence context is created when the entity
manager is created and kept until the entity manager is closed. In an
extended persistence context, all modification operations (persist,
merge, remove) executed outside a transaction are queued until the
persistence context is attached to a transaction. The transaction
typically occurs at the user process end, allowing the whole process to
be committed or rollbacked. For application-managed entity manager only
support the extended persistence context.</para>
<para>A resource-local entity manager or an entity manager created with
<literal>EntityManagerFactory.createEntityManager()</literal>
(application-managed) has a one-to-one relationship with a persistence
context. In other situations <emphasis>persistence context
propagation</emphasis> occurs.</para>
</section>
<section id="architecture-ejb-persistctxpropagation">
<title>Persistence context propagation</title>
<para>Persistence context propagation occurs for container-managed
entity managers.</para>
<para>In a transaction-scoped container managed entity manager (common
case in a Java EE environment), the JTA transaction propagation is the
same as the persistence context resource propagation. In other words,
container-managed transaction-scoped entity managers retrieved within a
given JTA transaction all share the same persistence context. In
Hibernate terms, this means all managers share the same session.</para>
<para>Important: persistence context are never shared between different
JTA transactions or between entity manager that do not came from the
same entity manager factory. There are some noteworthy exceptions for
context propagation when using extended persistence contexts:</para>
<itemizedlist>
<listitem>
<para>If a stateless session bean, message-driven bean, or stateful
session bean with a transaction-scoped persistence context calls a
stateful session bean with an extended persistence context in the
same JTA transaction, an
<classname>IllegalStateException</classname> is thrown.</para>
</listitem>
<listitem>
<para>If a stateful session bean with an extended persistence
context calls as stateless session bean or a stateful session bean
with a transaction-scoped persistence context in the same JTA
transaction, the persistence context is propagated.</para>
</listitem>
<listitem>
<para>If a stateful session bean with an extended persistence
context calls a stateless or stateful session bean in a different
JTA transaction context, the persistence context is not
propagated.</para>
</listitem>
<listitem>
<para>If a stateful session bean with an extended persistence
context instantiates another stateful session bean with an extended
persistence context, the extended persistence context is inherited
by the second stateful session bean. If the second stateful session
bean is called with a different transaction context than the first,
an IllegalStateException is thrown.</para>
</listitem>
<listitem>
<para>If a stateful session bean with an extended persistence
context calls a stateful session bean with a different extended
persistence context in the same transaction, an
<classname>IllegalStateException</classname> is thrown.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section id="architecture-javase" revision="1">
<title>Java SE environments</title>
<para>In a Java SE environment only extended context application-managed
entity managers are available. You can retrieve an entity manger using the
<literal>EntityManagerFactory</literal> API. Only resource-local entity
managers are available. In other words, JTA transactions and persistence
context propagation are not supported in Java SE (you will have to
propagate the persistence context yourself, e.g. using the thread local
session pattern popular in the Hibernate community).</para>
<para>Extended context means that a persistence context is created when
the entity manager is retrieved (using
<literal>EntityManagerFactory.createEntityManager(...)</literal> ) and
closed when the entity manager is closed. Many resource-local transaction
share the same persistence context, in this case.</para>
</section>
</chapter>