-
Notifications
You must be signed in to change notification settings - Fork 130
/
ref_guide_deploy.xml
312 lines (309 loc) · 11.3 KB
/
ref_guide_deploy.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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright 2006 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<chapter id="ref_guide_deploy">
<title>
Deployment
</title>
<para>
OpenJPA deployment includes choosing a factory deployment strategy, and in a
managed environment, optionally integrating with your application server's
managed and XA transactions. This chapter examines each aspect of deployment in
turn.
</para>
<section id="ref_guide_deploy_factory">
<title>
Factory Deployment
</title>
<para>
OpenJPA offers two <classname>EntityManagerFactory</classname>
deployment options.
</para>
<section id="ref_guide_deploy_factory_standalone">
<title>
Standalone Deployment
</title>
<indexterm zone="ref_guide_deploy_factory_standalone">
<primary>
deployment
</primary>
<secondary>
standalone
</secondary>
<seealso>
Persistence
</seealso>
</indexterm>
<para>
The JPA Overview describes the <classname>javax.persistence.Persistence
</classname> class. You can use <classname>Persistence</classname> to obtain
<classname>EntityManagerFactory</classname> instances, as demonstrated in
<xref linkend="jpa_overview_persistence"/>. OpenJPA also extends
<classname>Persistence</classname> to add additional <classname>
EntityManagerFactory</classname> creation methods. The <classname>
org.apache.openjpa.persistence.OpenJPAPersistence</classname> class
<ulink url="../javadoc/org/apache/openjpa/persistence/OpenJPAPersistence.html">
Javadoc</ulink> details these extensions.
</para>
<para>
After obtaining the factory, you can cache it for all <classname>
EntityManager</classname> creation duties. OpenJPA factories support being
bound to JNDI as well.
</para>
</section>
<section id="ref_guide_deploy_inject">
<title>
EntityManager Injection
</title>
<para>
Java EE 5 application servers allow you to <emphasis>inject</emphasis>
entity managers into your session beans using the <literal>PersistenceContext
</literal> annotation. See your application server documentation for details.
</para>
</section>
</section>
<section id="ref_guide_enterprise_trans">
<title>
Integrating with the Transaction Manager
</title>
<indexterm zone="ref_guide_enterprise_trans">
<primary>
transactions
</primary>
<secondary>
managed
</secondary>
</indexterm>
<indexterm zone="ref_guide_enterprise_trans">
<primary>
TransactionManager
</primary>
<secondary>
integration
</secondary>
</indexterm>
<indexterm>
<primary>
managed transactions
</primary>
<see>
transactions
</see>
</indexterm>
<indexterm>
<primary>
TransactionMode
</primary>
</indexterm>
<para>
OpenJPA <classname>EntityManager</classname>s have the ability to automatically
synchronize their transactions with an external transaction manager. Whether
or not <classname>EntityManager</classname>s from a given <classname>
EntityManagerFactory</classname> exhibit this behavior by default depends on
the transaction type you set for the factory's persistence unit in
your <filename>persistence.xml</filename> file. OpenJPA uses the given
transaction type internally to set the
<link linkend="openjpa.TransactionMode"><literal>openjpa.TransactionMode
</literal></link> configuration property. This property accepts the following
modes:
</para>
<itemizedlist>
<listitem>
<para>
<literal>local</literal>: Perform transaction operations locally.
</para>
</listitem>
<listitem>
<para>
<literal>managed</literal>: Integrate with the application server's managed
global transactions.
</para>
</listitem>
</itemizedlist>
<para>
You can override the global transaction mode setting when you obtain an
<classname>EntityManager</classname> using the
<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManagerFactory.html">
<classname>EntityManagerFactory</classname></ulink>'s
<methodname>createEntityManager(Map props)</methodname> method. Simply set the
<literal>openjpa.TransactionMode</literal> key of the given <classname>Map
</classname> to the desired value.
</para>
<note>
<para>
You can also override the <literal>openjpa.ConnectionUserName</literal>,
<literal>openjpa.ConnectionPassword</literal>, and <literal>
openjpa.ConnectionRetainMode</literal> settings using the given <classname>
Map</classname>.
</para>
</note>
<para>
<indexterm><primary>ManagedRuntime</primary></indexterm>
In order to use global transactions, OpenJPA must be able to access the
application server's <classname>
javax.transaction.TransactionManager</classname>. OpenJPA can automatically
discover the transaction manager for most major application servers.
Occasionally, however, you might have to point OpenJPA to the transaction
manager for an unrecognized or non-standard application server setup. This is
accomplished through the <link linkend="openjpa.ManagedRuntime"><literal>
openjpa.ManagedRuntime</literal></link> configuration property. This
property describes an
<ulink url="../javadoc/org/apache/openjpa/ee/ManagedRuntime.html"><classname>
org.apache.openjpa.ee.ManagedRuntime</classname></ulink> implementation to use
for transaction manager discovery. You can specify your own implementation,
or use one of the built-ins:
</para>
<itemizedlist>
<listitem>
<para>
<literal>auto</literal>: This is the default. It is an alias for the
<ulink url="../javadoc/org/apache/openjpa/ee/AutomaticManagedRuntime.html">
<classname>org.apache.openjpa.ee.AutomaticManagedRuntime</classname></ulink>
class. This managed runtime is able to automatically integrate with several
common application servers.
</para>
</listitem>
<listitem>
<para>
<literal>invocation</literal>: An alias for the
<ulink url="../javadoc/org/apache/openjpa/ee/InvocationManagedRuntime.html">
<classname>org.apache.openjpa.ee.InvocationManagedRuntime</classname></ulink>
class. You can configure this runtime to invoke any static
method in order to obtain the appserver's transaction manager.
</para>
</listitem>
<listitem>
<para>
<literal>jndi</literal>: An alias for the
<ulink url="../javadoc/org/apache/openjpa/ee/JNDIManagedRuntime.html">
<classname>org.apache.openjpa.ee.JNDIManagedRuntime</classname></ulink>
class. You can configure this runtime to look up the transaction manager at
any JNDI location.
</para>
</listitem>
</itemizedlist>
<para>
See the Javadoc for of each class for details on the bean properties
you can pass to these plugins in your configuration string.
</para>
<example id="ref_guide_enterprise_transex">
<title>Configuring Transaction Manager Integration</title>
<programlisting>
<![CDATA[<property name="openjpa.TransactionMode" value="managed"/>
<property name="openjpa.ManagedRuntime" value="jndi(TransactionManagerName=java:/TransactionManager)"/>]]>
</programlisting>
</example>
</section>
<section id="ref_guide_enterprise_xa">
<title>
XA Transactions
</title>
<indexterm zone="ref_guide_enterprise_xa">
<primary>
transactions
</primary>
<secondary>
XA
</secondary>
</indexterm>
<indexterm>
<primary>
XA transactions
</primary>
<see>
transactions
</see>
</indexterm>
<para>
The X/Open Distributed Transaction Processing (X/Open DTP) model, designed by
<ulink url="http://www.xopen.org">Open Group</ulink> (a vendor consortium),
defines a standard communication architecture that provides the following:
</para>
<itemizedlist>
<listitem>
<para>
Concurrent execution of applications on shared resources.
</para>
</listitem>
<listitem>
<para>
Coordination of transactions across applications.
</para>
</listitem>
<listitem>
<para>
Components, interfaces, and protocols that define the architecture and provide
portability of applications.
</para>
</listitem>
<listitem>
<para>
Atomicity of transaction systems.
</para>
</listitem>
<listitem>
<para>
Single-thread control and sequential function-calling.
</para>
</listitem>
</itemizedlist>
<para>
The X/Open DTP XA standard defines the application programming interfaces that a
resource manager uses to communicate with a transaction manager. The XA
interfaces enable resource managers to join transactions, to perform two-phase
commit, and to recover in-doubt transactions following a failure.
</para>
<section id="ref_guide_enterprise_xa_req">
<title>
Using OpenJPA with XA Transactions
</title>
<para>
OpenJPA supports XA-compliant transactions when used in a properly configured
managed environment. The following components are required:
</para>
<itemizedlist>
<listitem>
<para>
A managed environment that provides an XA compliant transaction manager.
Examples of this are application servers such as WebLogic or JBoss.
</para>
</listitem>
<listitem>
<para>
Instances of a <classname>javax.sql.XADataSource</classname> for each of the
<classname>DataSource</classname>s that OpenJPA will use.
</para>
</listitem>
</itemizedlist>
<para>
Given these components, setting up OpenJPA to participate in distributed
transactions is a simple two-step process:
</para>
<orderedlist>
<listitem>
<para>
Integrate OpenJPA with your application server's transaction manager, as
detailed in <xref linkend="ref_guide_enterprise_trans"/> above.
</para>
</listitem>
<listitem>
<para>
Point OpenJPA at an enlisted <classname>XADataSource</classname>, and configure
a second non-enlisted data source. See
<xref linkend="ref_guide_dbsetup_thirdparty_enlist"/>.
</para>
</listitem>
</orderedlist>
</section>
</section>
</chapter>