openjpa/openjpa-project/src/doc/manual/ref_guide_deploy.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 several <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="../apidocs/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.
            </para>
        </section>
        <section id="ref_guide_deploy_inject">
            <title>
                EntityManager Injection
            </title>
            <!-- ### -->
            <para>
TBD
            </para>
        </section>
    </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 JBoss and WebLogic.
                    </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>
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>