mirror of https://github.com/apache/openjpa.git
297 lines
11 KiB
XML
297 lines
11 KiB
XML
<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>
|