You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by mp...@apache.org on 2006/08/22 23:28:55 UTC
svn commit: r433761 [1/18] - in /incubator/openjpa/trunk/openjpa-project: ./
src/doc/manual/
Author: mprudhom
Date: Tue Aug 22 14:28:53 2006
New Revision: 433761
URL: http://svn.apache.org/viewvc?rev=433761&view=rev
Log:
Split up the documentation into multiple chunks for easier management.
Added:
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_arch.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_em.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_intro.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_mapping.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_pc.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_persistence.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_sqlquery.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_trans.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_why.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_resources.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/openjpa_intro.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_intro.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_logging.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_meta.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/samples_guide.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml
Modified:
incubator/openjpa/trunk/openjpa-project/pom.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/manual.xml
Modified: incubator/openjpa/trunk/openjpa-project/pom.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/pom.xml?rev=433761&r1=433760&r2=433761&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/pom.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/pom.xml Tue Aug 22 14:28:53 2006
@@ -47,13 +47,21 @@
basedir="${project.basedir}/src/doc/manual"
destdir="${project.basedir}/target/filtered-site/resources/manual"
style="manual-xhtml.xsl"
- classpathref="maven.runtime.classpath"/>
+ classpathref="maven.runtime.classpath">
+ <factory name="org.apache.xalan.processor.TransformerFactoryImpl">
+ <attribute name="http://xml.apache.org/xalan/features/optimize" value="true"/>
+ </factory>
+ </style>
<style includes="**/manual.xml"
force="true"
basedir="${project.basedir}/src/doc/manual"
destdir="${project.basedir}/target/filtered-site/resources/manual"
style="manual-xhtml-chunk.xsl"
- classpathref="maven.runtime.classpath"/>
+ classpathref="maven.runtime.classpath">
+ <factory name="org.apache.xalan.processor.TransformerFactoryImpl">
+ <attribute name="http://xml.apache.org/xalan/features/optimize" value="true"/>
+ </factory>
+ </style>
</tasks>
</configuration>
<goals>
Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_arch.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_arch.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_arch.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_arch.xml Tue Aug 22 14:28:53 2006
@@ -0,0 +1,196 @@
+
+ <chapter id="jpa_overview_arch">
+ <title>EJB Persistence Architecture</title>
+ <indexterm zone="jpa_overview_arch">
+ <primary>EJB</primary>
+ <secondary>architecture</secondary>
+ </indexterm>
+ <para>
+ The diagram below illustrates the relationships between the primary
+ components of the EJB architecture.
+ </para>
+ <mediaobject>
+ <imageobject>
+<!-- PNG image data 400 x 256 (see README) -->
+ <imagedata fileref="img/jpa-arch.png" width="267px"/>
+ </imageobject>
+ <textobject>
+ <phrase>EJB architecture</phrase>
+ </textobject>
+ </mediaobject>
+ <note>
+ <para>
+ A number of the depicted interfaces are only required outside of
+ an EJB3-compliant application server. In an application server,
+ <classname>EntityManager</classname> instances are typically injected,
+ rendering the <classname>EntityManagerFactory</classname> unnecessary.
+ Also, transactions within an application server
+ are handled using standard application server transaction controls.
+ Thus, the <classname>EntityTransaction</classname> also goes unused.
+ </para>
+ </note>
+ <itemizedlist>
+ <listitem>
+ <para><indexterm><primary>Persistence</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_persistence"><classname>Persistence</classname></link></emphasis>:
+ The <classname>javax.persistence.Persistence</classname> class
+ contains static helper methods to obtain
+ <classname>EntityManagerFactory</classname> instances in a
+ vendor-neutral fashion.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>EntityManagerFactory</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_emfactory"><classname>EntityManagerFactory</classname></link></emphasis>: The <classname>javax.persistence.EntityManagerFactory
+ </classname> class is a factory for <classname>
+ EntityManager</classname>s.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>EntityManager</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_em"><classname>EntityManager</classname></link></emphasis>:
+ The <classname>javax.persistence.EntityManager</classname> is the
+ primary EJB persistence interface used by applications.
+ Each <classname>EntityManager</classname> manages a set of
+ persistent objects, and has APIs to insert new objects and delete
+ existing ones. When used outside the container, there is a
+ one-to-one relationship between an
+ <classname>EntityManager</classname> and an <classname>
+ EntityTransaction</classname>. <classname>
+ EntityManager</classname>s also act as factories for
+ <classname>Query</classname> instances.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>entity</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_pc"><classname>Entity</classname></link></emphasis>:
+ Entites are persistent objects that represent datastore records.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>EntityTransaction</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_trans"><classname>EntityTransaction</classname></link></emphasis>:
+ Each <classname>EntityManager</classname> has a one-to-one
+ relation with a single
+ <classname>javax.persistence.EntityTransaction</classname>.
+ <classname>EntityTransaction</classname>s allow operations on
+ persistent data to be grouped into units of work that either
+ completely succeed or completely fail, leaving the datastore
+ in its original state. These all-or-nothing operations are
+ important for maintaining data integrity.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>Query</primary></indexterm><indexterm><primary>EJB3 Persistence Query Language</primary><see>JPQL</see></indexterm><indexterm><primary>JPQL</primary></indexterm><indexterm><primary>EJB</primary><secondary>query language</secondary><see>JPQL</see></indexterm><indexterm><primary>Structured Query Language</primary><see>SQL</see></indexterm><indexterm><primary>SQL</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_query"><classname>Query</classname></link></emphasis>: The
+ <classname>javax.persistence.Query</classname> interface is
+ implemented by each EJB vendor to find persistent objects
+ that meet certain criteria. EJB standardizes support
+ for queries using both the EJB Query Language (JPQL) and
+ the Structured Query Language (SQL). You obtain
+ <classname>Query</classname> instances from an
+ <classname>EntityManager</classname>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The example below illustrates how the EJB interfaces interact to
+ execute an JPQL query and update persistent objects. The example
+ assumes execution outside a container.
+ </para>
+ <example id="jpa_overview_arch_interact_outside">
+ <title>Interaction of Interfaces Outside Container</title>
+ <programlisting format="linespecific">
+// get an EntityManagerFactory using the Persistence class; typically
+// the factory is cached for easy repeated use
+EntityManagerFactory factory = Persistence.createEntityManagerFactory (null);
+
+// get an EntityManager from the factory
+EntityManager em = factory.createEntityManager (PersistenceContextType.EXTENDED);
+
+// updates take place within transactions
+EntityTransaction tx = em.getTransaction ();
+tx.begin ();
+
+// query for all employees who work in our research division
+// and put in over 40 hours a week average
+Query query = em.createQuery ("select e from Employee e where "
+ + "e.division.name = 'Research' AND e.avgHours > 40");
+List results = query.getResultList ();
+
+// give all those hard-working employees a raise
+for (Object res : results)
+{
+ Employee emp = (Employee) res;
+ emp.setSalary (emp.getSalary () * 1.1);
+}
+
+// commit the updates and free resources
+tx.commit ();
+em.close ();
+factory.close ();
+</programlisting>
+ </example>
+ <para>
+ Within a container, the <classname>EntityManager</classname> will be
+ injected and transactional handled declaratively. Thus, the in-container
+ version of the example consists entirely of business logic:
+ </para>
+ <example id="jpa_overview_arch_interact_inside">
+ <title>Interaction of Interfaces Inside Container</title>
+ <programlisting format="linespecific">
+// query for all employees who work in our research division
+// and put in over 40 hours a week average - note that the EntityManager em
+// is injected using a @Resource annotation
+Query query = em.createQuery ("select e from Employee e where "
+ + "e.division.name = 'Research' and e.avgHours > 40");
+List results = query.getResultList ();
+
+// give all those hard-working employees a raise
+for (Object res : results)
+{
+ emp = (Employee) res;
+ emp.setSalary (emp.getSalary () * 1.1);
+}
+</programlisting>
+ </example>
+ <para>
+ The remainder of this document explores the EJB interfaces in
+ detail. We present them in roughly the order that you will use them as you
+ develop your application.
+ </para>
+ <section id="jpa_overview_arch_exceptions">
+ <title>EJB Exceptions</title>
+ <indexterm zone="jpa_overview_arch_exceptions">
+ <primary>EJB</primary>
+ <secondary>exceptions</secondary>
+ <seealso>exceptions</seealso>
+ </indexterm>
+ <indexterm>
+ <primary>exceptions</primary>
+ <secondary>EJB</secondary>
+ </indexterm>
+ <mediaobject>
+ <imageobject>
+<!-- PNG image data, 427 x 355 (see README) -->
+ <imagedata fileref="img/jpa-exceptions.png" width="285px"/>
+ </imageobject>
+ <textobject>
+ <phrase>EJB persistence exception architecture</phrase>
+ </textobject>
+ </mediaobject>
+ <para>
+ The diagram above depicts the EJB persistence exception architecture.
+ All exceptions are unchecked. EJB persistence uses
+ standard exceptions where appropriate, most notably <classname>
+ IllegalArgumentException</classname>s and <classname>
+ IllegalStateException</classname>s. The specification also provides
+ a few EJB-specific exceptions in the <literal>javax.persistence
+ </literal> package. These exceptions should be self-explanatory. See
+ the <ulink url="http://java.sun.com/javaee/5/docs/api">Javadoc</ulink> for
+ additional details on EJB exceptions.
+ </para>
+ <note>
+ <para>
+ All exceptions thrown by OpenJPA implement
+ <ulink url="../apidocs/org/apache/openjpa/util/ExceptionInfo.html"><classname>
+ org.apache.openjpa.util.ExceptionInfo</classname></ulink> to provide you with
+ additional error information.
+ </para>
+ </note>
+ </section>
+ </chapter>
Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml Tue Aug 22 14:28:53 2006
@@ -0,0 +1,18 @@
+
+ <chapter id="jpa_overview_conclusion">
+ <title>Conclusion</title>
+ <para>
+ This concludes our overview of the EJB persistence specification. The
+ <link linkend="jpa_tutorials_intro">OpenJPA EJB Tutorials</link>
+ continue your EJB education with step-by-step instructions for
+ building simple EJB persistence applications. The
+ <link linkend="ref_guide_intro">OpenJPA Reference Guide</link> contains
+ detailed documentation on all aspects of the OpenJPA EJB persistence
+ implementation and core development tools.
+<!-- ### JDO2MIG
+ Finally,
+ the <link linkend="gui_intro">Workbench Guide</link> teaches you how to
+ use the OpenJPA Development Workbench for GUI-driven development.
+-->
+ </para>
+ </chapter>
Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_em.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_em.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_em.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_em.xml Tue Aug 22 14:28:53 2006
@@ -0,0 +1,714 @@
+
+ <chapter id="jpa_overview_em">
+ <title>EntityManager</title>
+ <indexterm zone="jpa_overview_em">
+ <primary>EntityManager</primary>
+ </indexterm>
+ <mediaobject>
+ <imageobject>
+<!-- PNG image data, 283 x 391 (see README) -->
+ <imagedata fileref="img/entitymanager.png" width="189px"/>
+ </imageobject>
+ </mediaobject>
+ <para>
+ The diagram above presents an overview of the
+ <classname>EntityManager</classname> interface. For a complete
+ treatment of the <classname>EntityManager</classname> API, see the
+ <ulink url="jdo-javadoc/javax/jdo/EntityManager.html">
+ Javadoc</ulink> documentation. Methods whose parameter signatures consist
+ of an ellipsis (...) are overloaded to take multiple parameter types.
+ </para>
+ <note>
+ <para>
+ OpenJPA extends the standard <classname>EntityManager</classname>
+ interface with the
+ <ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><classname>org.apache.openjpa.persistence.OpenJPAEntityManager</classname></ulink>
+ interface to provide additional functionality.
+ </para>
+ </note>
+ <para>
+ The <classname>EntityManager</classname> is the primary interface
+ used by application developers to interact with the EJB persistence runtime.
+ The methods of the <classname>EntityManager</classname> can be
+ divided into the following functional categories:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para><classname>Transaction</classname> association.</para>
+ </listitem>
+ <listitem>
+ <para>Entity lifecycle management.</para>
+ </listitem>
+ <listitem>
+ <para>Entity identity management.</para>
+ </listitem>
+ <listitem>
+ <para>Cache management.</para>
+ </listitem>
+ <listitem>
+ <para><classname>Query</classname> factory.</para>
+ </listitem>
+ <listitem>
+ <para>Closing.</para>
+ </listitem>
+ </itemizedlist>
+ <section id="jpa_overview_em_trans">
+ <title>Transaction Association</title>
+ <indexterm zone="jpa_overview_em_trans">
+ <primary>EntityManager</primary>
+ <secondary>obtaining the Transaction</secondary>
+ <seealso>transactions</seealso>
+ </indexterm>
+ <indexterm zone="jpa_overview_em_trans">
+ <primary>Transaction</primary>
+ <secondary>obtaining from EntityManager</secondary>
+ </indexterm>
+ <programlisting format="linespecific">
+public EntityTransaction getTransaction ();
+</programlisting>
+ <para>
+ Every <classname>EntityManager</classname> has a one-to-one
+ relation with an <link linkend="jpa_overview_trans"><classname>EntityTransaction</classname></link> instance. In
+ fact, many vendors use a single class to implement both
+ the <classname>EntityManager</classname> and
+ <classname>EntityTransaction</classname> interfaces. If your
+ application requires multiple concurrent transactions, you will
+ use multiple <classname>EntityManager</classname>s.
+ </para>
+ <para>
+ You can retrieve the <classname>EntityTransaction</classname>
+ associated with an <classname>EntityManager</classname> through the
+ <methodname>getTransaction</methodname> method. Note that most
+ most EJB persistence implementations can integrate with an application
+ server's managed transactions. If you take advantage of this feature,
+ you will control transactions by declarative demarcation or through
+ the Java Transaction API (JTA) rather than through the
+ <classname>EntityTransaction</classname>.
+ </para>
+ </section>
+ <section id="jpa_overview_em_lifecycle">
+ <title>Entity Lifecycle Management</title>
+ <indexterm zone="jpa_overview_em_lifecycle">
+ <primary>EntityManager</primary>
+ <secondary>lifecycle operations</secondary>
+ </indexterm>
+ <para><classname>EntityManager</classname>s perform several actions
+ that affect the lifecycle state of entity instances.
+ </para>
+ <programlisting format="linespecific">
+public void persist (Object entity);
+</programlisting>
+ <para><indexterm><primary>EntityManager</primary><secondary>persist</secondary></indexterm><indexterm><primary>persist</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>persistent objects</primary><secondary>persisting</secondary></indexterm>
+ Transitions new instances to managed. On the next flush or commit,
+ the newly persisted instances will be inserted into the datastore.
+ </para>
+ <para>
+ For a given entity <literal>A</literal>, the <methodname>persist
+ </methodname> method behaves as follows:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a new entity, it becomes managed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is an existing managed entity, it is
+ ignored. However, the persist operation cascades as
+ defined below.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a removed entity, it becomes managed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a detached entity, an
+ <classname>IllegalArgumentException</classname> is thrown.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The persist operation recurses on all relation fields of
+ <literal>A</literal> whose
+ <link linkend="jpa_overview_meta_cascade">cascades</link>
+ include <literal>CascadeType.PERSIST</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ This action can only be used in the context of an active transaction.
+ </para>
+ <programlisting format="linespecific">
+public void remove (Object entity);
+</programlisting>
+ <para><indexterm><primary>EntityManager</primary><secondary>remove</secondary></indexterm><indexterm><primary>remove</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>persistent objects</primary><secondary>deleting</secondary></indexterm>
+ Transitions managed instances to removed. The instances will be
+ deleted from the datastore on the next flush or commit. Accessing
+ a removed entity has undefined results.
+ </para>
+ <para>
+ For a given entity <literal>A</literal>, the <methodname>remove
+ </methodname> method behaves as follows:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a new entity, it is ignored.
+ However, the remove operation cascades as defined below.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is an existing managed entity, it
+ becomes removed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a removed entity, it is ignored.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a detached entity, an
+ <classname>IllegalArgumentException</classname> is thrown.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The remove operation recurses on all relation fields of
+ <literal>A</literal> whose
+ <link linkend="jpa_overview_meta_cascade">cascades</link>
+ include <literal>CascadeType.REMOVE</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ This action can only be used in the context of an active transaction.
+ </para>
+ <programlisting format="linespecific">
+public void refresh (Object entity);
+</programlisting>
+ <para><indexterm><primary>EntityManager</primary><secondary>refresh</secondary></indexterm><indexterm><primary>refresh</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>persistent objects</primary><secondary>refreshing state</secondary></indexterm><indexterm><primary>transactions</primary><secondary>optimistic</secondary></indexterm>
+ Use the <methodname>refresh</methodname> action to make sure
+ the persistent state of an instance is synchronized with the
+ values in the datastore. <methodname>refresh</methodname>
+ is intended for long-running optimistic transactions in
+ which there is a danger of seeing stale data.
+ </para>
+ <para>
+ For a given entity <literal>A</literal>, the <methodname>refresh
+ </methodname> method behaves as follows:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a new entity, it is ignored.
+ However, the remove operation cascades as defined below.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is an existing managed entity, its
+ state is refreshed from the datastore.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a removed entity, it is ignored.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a detached entity, an
+ <classname>IllegalArgumentException</classname> is thrown.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The refresh operation recurses on all relation fields of
+ <literal>A</literal> whose
+ <link linkend="jpa_overview_meta_cascade">cascades</link>
+ include <literal>CascadeType.REFRESH</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <programlisting format="linespecific">
+public Object merge (Object entity);
+</programlisting>
+ <para><indexterm><primary>EntityManager</primary><secondary>merge</secondary><seealso>detachment</seealso></indexterm><indexterm><primary>detachment</primary><secondary>EJB</secondary></indexterm><indexterm><primary>merge</primary><seealso>detachment</seealso></indexterm><indexterm><primary>data transfer object</primary></indexterm><indexterm><primary>value object</primary></indexterm>
+ A common use case for an application running in a servlet or
+ application server is to "detach" objects from all server resources,
+ modify them, and then "attach" them again. For example, a servlet
+ might store persistent data in a user session between a modification
+ based on a series of web forms. Between each form request, the web
+ container might decide to serialize the session, requiring that the
+ stored persistent state be disassociated from any other
+ resources. Similarly, a client/server application might
+ transfer persistent objects to a client via serialization, allow the
+ client to modify their state, and then have the client return the
+ modified data in order to be saved. This is sometimes referred to as
+ the <emphasis>data transfer object</emphasis> or <emphasis>value
+ object</emphasis> pattern, and it allows fine-grained manipulation
+ of data objects without incurring the overhead of multiple remote
+ method invocations.
+ </para>
+ <para>
+ EJB persistence provides support for this pattern by automatically
+ detaching entities when they are serialized or when a persistence
+ context ends (see
+ <xref linkend="jpa_overview_emfactory_perscontext"/> for an
+ exploration of persistence contexts). The EJB persistence
+ <emphasis>merge</emphasis> API re-attaches detached entities.
+ This allows you to detach a persistent instance, modify the
+ detached instance offline, and merge the instance back into an
+ <classname>EntityManager</classname> (either the same one that
+ detached the instance, or a new one). The changes will then be
+ applied to the existing instance from the datastore.
+ </para>
+ <para>
+ A detached entity maintains its persistent identity, but cannot load
+ additional state from the datastore. Accessing any persistent field or
+ property that was not loaded at the time of detachment has undefined
+ results. Also, be sure not to alter the version or identity fields of
+ detached instances if you plan on merging them later.
+ </para>
+ <para>
+ The <methodname>merge</methodname> method returns a managed copy of the
+ given detached entity. Changes made to the persistent state of the
+ detached entity are applied to this managed instance. Because merging
+ involves changing persistent state, you can only merge within a
+ transaction.
+ </para>
+ <para>
+ If you attempt to merge an instance whose representation has
+ changed in the datastore since detachment, the merge operation will
+ throw an exception, or the transaction in which you perform the
+ merge will fail on commit, just as if a normal optimistic conflict
+ were detected.
+ </para>
+ <note>
+ <para>
+ OpenJPA offers enhancements to EJB persistence detachment
+ functionality, including additional options to control which
+ fields are detached. See <xref linkend="ref_guide_detach"/>
+ in the Reference Guide for details.
+ </para>
+ </note>
+ <para>
+ For a given entity <literal>A</literal>, the <methodname>merge
+ </methodname> method behaves as follows:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a detached entity, its state
+ is copied into existing managed instance <literal>A'</literal>
+ of the same entity identity, or a new managed copy of
+ <literal>A</literal> is created.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a new entity, a new managed
+ entity <literal>A'</literal> is created and the state of
+ <literal>A</literal> is copied into <literal>A'</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is an existing managed entity, it is
+ ignored. However, the merge operation still cascades as
+ defined below.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <literal>A</literal> is a removed entity, an
+ <classname>IllegalArgumentException</classname> is thrown.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The merge operation recurses on all relation fields of
+ <literal>A</literal> whose
+ <link linkend="jpa_overview_meta_cascade">cascades</link>
+ include <literal>CascadeType.MERGE</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <programlisting format="linespecific">
+public void lock (Object entity, LockModeType mode);
+</programlisting>
+ <para><indexterm><primary>EntityManager</primary><secondary>lock</secondary></indexterm><indexterm><primary>locking</primary><seealso>EntityManager</seealso></indexterm>
+ This method locks the given entity using the named mode. The
+ <ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/LockmodeType.html"><classname>javax.persistence.LockModeType</classname></ulink> enum
+ defines two modes:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>READ</literal>: Other transactions may concurrently
+ read the object, but cannot concurrently update it.
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>WRITE</literal>: Other transactions cannot
+ concurrently read or write the object. When a transaction
+ is committed that holds WRITE locks on any entites, those
+ entites will have their version incremented even if
+ the entities themselves did not change in the transaction.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+ OpenJPA has additional APIs for controlling object locking. See
+ <xref linkend="ref_guide_locking"/> in the Reference Guide for
+ details.
+ </para>
+ </note>
+ <para>
+ The following diagram illustrates the lifecycle of an entity with
+ respect to the APIs presented in this section.
+ </para>
+ <mediaobject>
+ <imageobject>
+<!-- PNG image data, 445 x 337 (see README) -->
+ <imagedata fileref="img/jpa-state-transitions.png" width="297px"/>
+ </imageobject>
+ </mediaobject>
+ </section>
+ <section id="jpa_overview_em_lifeexamples">
+ <title>Lifecycle Examples</title>
+ <para>
+ The examples below demonstrate how to use the lifecycle methods
+ presented in the previous section. The examples are appropriate for
+ out-of-container use. Within a container, <classname>
+ EntityManager</classname>s are usually injected, and transactions are
+ usually managed. You would therefore omit the
+ <methodname>createEntityManager</methodname> and <methodname>close
+ </methodname> calls, as well as all transaction demarcation code.
+ </para>
+ <example id="jpa_overview_em_lifecycle_persist">
+ <title>Persisting Objects</title>
+ <indexterm>
+ <primary>persistent objects</primary>
+ <secondary>persisting</secondary>
+ <tertiary>example</tertiary>
+ </indexterm>
+ <programlisting format="linespecific">
+// create some objects
+Magazine mag = new Magazine ("1B78-YU9L", "JavaWorld");
+
+Company pub = new Company ("Weston House");
+pub.setRevenue (1750000D);
+mag.setPublisher (pub);
+pub.addMagazine (mag);
+
+Article art = new Article ("EJB Rules!", "Transparent Object Persistence");
+art.addAuthor (new Author ("Fred", "Hoyle"));
+mag.addArticle (art);
+
+// persist
+EntityManager em = emf.createEntityManager ();
+em.getTransaction ().begin ();
+em.persist (mag);
+em.persist (pub);
+em.persist (art);
+em.getTransaction ().commit ();
+
+// or we could continue using the EntityManager...
+em.close ();
+</programlisting>
+ </example>
+ <example id="jpa_overview_em_lifecycle_update">
+ <title>Updating Objects</title>
+ <indexterm>
+ <primary>persistent objects</primary>
+ <secondary>updating</secondary>
+ <tertiary>example</tertiary>
+ </indexterm>
+ <programlisting format="linespecific">
+Magazine.MagazineId mi = new Magazine.MagazineId ();
+mi.isbn = "1B78-YU9L";
+mi.title = "JavaWorld";
+
+// updates should always be made within transactions; note that
+// there is no code explicitly linking the magazine or company
+// with the transaction; EJB automatically tracks all changes
+EntityManager em = emf.createEntityManager ();
+em.getTransaction ().begin ();
+Magazine mag = em.find (Magazine.class, mi);
+mag.setPrice (5.99);
+Company pub = mag.getPublisher ();
+pub.setRevenue (1750000D);
+em.getTransaction ().commit ();
+
+// or we could continue using the EntityManager...
+em.close ();
+</programlisting>
+ </example>
+ <example id="jpa_overview_em_lifecycle_delete">
+ <title>Removing Objects</title>
+ <indexterm>
+ <primary>persistent objects</primary>
+ <secondary>deleting</secondary>
+ <tertiary>example</tertiary>
+ </indexterm>
+ <programlisting format="linespecific">
+// assume we have an object id for the company whose subscriptions
+// we want to delete
+Object oid = ...;
+
+// deletes should always be made within transactions
+EntityManager em = emf.createEntityManager ();
+em.getTransaction ().begin ();
+Company pub = (Company) em.find (Company.class, oid);
+for (Subscription sub : pub.getSubscriptions ())
+ em.remove (sub);
+pub.getSubscriptions ().clear ();
+em.getTransaction ().commit ();
+
+// or we could continue using the EntityManager...
+em.close ();
+</programlisting>
+ </example>
+ <example id="jpa_overview_em_detachex">
+ <title>Detaching and Merging</title>
+ <para>
+ This example demonstrates a common client/server scenario. The
+ client requests objects and makes changes to them, while the
+ server handles the object lookups and transactions.
+ </para>
+ <programlisting format="linespecific">
+// CLIENT:
+// requests an object with a given oid
+Record detached = (Record) getFromServer (oid);
+
+...
+
+// SERVER:
+// send object to client; object detaches on EM close
+Object oid = processClientRequest ();
+EntityManager em = emf.createEntityManager ();
+Record record = em.find (Record.class, oid);
+em.close ();
+sendToClient (record);
+
+...
+
+// CLIENT:
+// makes some modifications and sends back to server
+detached.setSomeField ("bar");
+sendToServer (detached);
+
+...
+
+// SERVER:
+// merges the instance and commit the changes
+Record modified = (Record) processClientRequest ();
+EntityManager em = emf.createEntityManager ();
+em.getTransaction ().begin ();
+Record merged = (Record) em.merge (modified);
+merged.setLastModified (System.currentTimeMillis ());
+merged.setModifier (getClientIdentityCode ());
+em.getTransaction ().commit ();
+em.close ();
+</programlisting>
+ </example>
+ </section>
+ <section id="jpa_overview_em_identity">
+ <title>Entity Identity Management</title>
+ <para>
+ Each <classname>EntityManager</classname> is responsible for
+ managing the persistent identities of the managed objects in the
+ persistence context. The following methods allow you to interact
+ with the management of persistent identities. The behavior of these
+ methods is deeply affected by the persistence context type of the
+ <classname>EntityManager</classname>; see
+ <xref linkend="jpa_overview_emfactory_perscontext"/> for an
+ explanation of persistence contexts.
+ </para>
+ <programlisting format="linespecific">
+public <T> T find (Class<T> cls, Object oid);
+</programlisting>
+ <para><indexterm><primary>EntityManager</primary><secondary>find</secondary><seealso>identity</seealso></indexterm><indexterm><primary>find</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>identity</primary><secondary>retrieving objects by identity</secondary></indexterm>
+ This method returns the persistent instance of the given type with
+ the given persistent identity. If the instance is already present in
+ the current persistence context, the cached version will be returned.
+ Otherwise, a new instance will be constructed and loaded with
+ state from the datastore. If no entity with the given type and identity
+ exists in the datastore, this method returns null.
+ </para>
+ <programlisting format="linespecific">
+public <T> T getReference (Class<T> cls, Object oid);
+</programlisting>
+ <para><indexterm><primary>EntityManager</primary><secondary>getReference</secondary><seealso>identity</seealso></indexterm><indexterm><primary>getReference</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>identity</primary><secondary>retrieving objects by identity</secondary></indexterm><indexterm><primary>EntityNotFoundException</primary></indexterm>
+ This method is similar to <methodname>find</methodname>, but does not
+ necessarily go to the database when the entity is not found in cache.
+ The implementation may construct a <emphasis>hollow</emphasis> entity
+ and return it to you instead. Hollow entities do not have any
+ state loaded. The state only gets loaded when you attempt to access
+ a persistent field. At that time, the implementation may throw an
+ <classname>EntityNotFoundException</classname> if it discovers that
+ the entity does not exist in the datastore. The implementation may
+ also throw an <classname>EntityNotFoundException</classname> from
+ the <methodname>getReference</methodname> method itself. Unlike
+ <methodname>find</methodname>, <methodname>getReference</methodname>
+ does not return null.
+ </para>
+ <programlisting format="linespecific">
+public boolean contains (Object entity);
+</programlisting>
+ <para><indexterm><primary>EntityManager</primary><secondary>contains</secondary></indexterm><indexterm><primary>contains</primary><seealso>EntityManager</seealso></indexterm>
+ Returns true if the given entity is part of the current persistence
+ context, and false otherwise. Removed entities are not considered part
+ of the current persistence context.
+ </para>
+ </section>
+ <section id="jpa_overview_em_cache">
+ <title>Cache Management</title>
+ <indexterm zone="jpa_overview_em_cache">
+ <primary>EntityManager</primary>
+ <secondary>cache</secondary>
+ </indexterm>
+ <programlisting format="linespecific">
+public void flush ();
+</programlisting>
+ <para><indexterm><primary>EntityManager</primary><secondary>flush</secondary></indexterm><indexterm><primary>flush</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>transactions</primary><secondary>flushing changes before commit</secondary></indexterm>
+ The <methodname>flush</methodname> method writes any changes that have
+ been made in the current transaction to the datastore. If the
+ <classname>EntityManager</classname> does not already have a
+ connection to the datastore, it obtains one for the flush and retains
+ it for the duration of the transaction. Any exceptions during flush
+ cause the transaction to be marked for rollback.
+ See <xref linkend="jpa_overview_trans"/>.
+ </para>
+ <para>
+ Flushing requires an active transaction. If there isn't a transaction
+ in progress, the <methodname>flush</methodname> method throws a
+ <classname>TransactionRequiredException</classname>.
+ </para>
+ <programlisting format="linespecific">
+public FlushModeType getFlushMode ();
+public void setFlushMode (FlushModeType flushMode);
+</programlisting>
+ <para><indexterm><primary>EntityManager</primary><secondary>FlushMode</secondary></indexterm><indexterm><primary>FlushMode</primary></indexterm>
+ The <classname>EntityManager</classname>'s <literal>FlushMode</literal>
+ property controls whether to flush transactional changes before
+ executing queries. This allows the query results to take into account
+ changes you have made during the current transaction. Available
+ <ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/FlushModeType.html"><classname>javax.persistence.FlushModeType</classname></ulink> constants
+ are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>COMMIT</literal>: Only flush when committing, or
+ when told to do so through the <methodname>flush</methodname>
+ method. Query results may not take into account changes made
+ in the current transaction.
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>AUTO</literal>: The implementation is permitted to
+ flush before queries to ensure that the results reflect the
+ most recent object state.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ You can also set the flush mode on individual
+ <link linkend="jpa_overview_query"><classname>Query</classname></link>
+ instances.
+ </para>
+ <note>
+ <para>
+ OpenJPA only flushes before a query if the query might be affected
+ by data changed in the current transaction. Additionally,
+ OpenJPA allows fine-grained control over flushing behavior.
+ See the Reference Guide's
+ <xref linkend="ref_guide_dbsetup_retain"/>.
+ </para>
+ </note>
+ <programlisting format="linespecific">
+public void clear ();
+</programlisting>
+ <para><indexterm><primary>EntityManager</primary><secondary>clear</secondary></indexterm><indexterm><primary>clear</primary><seealso>EntityManager</seealso></indexterm>
+ Clearing the <classname>EntityManager</classname> effectively ends the
+ persistence context. All entities managed by
+ the <classname>EntityManager</classname> become detached.
+ </para>
+ </section>
+ <section id="jpa_overview_em_query">
+ <title>Query Factory</title>
+ <indexterm zone="jpa_overview_em_query">
+ <primary>EntityManager</primary>
+ <secondary>as Query factory</secondary>
+ <seealso>Query</seealso>
+ </indexterm>
+ <indexterm zone="jpa_overview_em_query">
+ <primary>Query</primary>
+ <secondary>creating</secondary>
+ </indexterm>
+ <programlisting format="linespecific">
+public Query createQuery (String query);
+</programlisting>
+ <para><classname>Query</classname> objects are used to find entities
+ matching certain criteria. The <methodname>createQuery</methodname>
+ method creates a query using the given EJB Query Language (JPQL)
+ string. See <xref linkend="jpa_overview_query"/> for details.
+ </para>
+ <programlisting format="linespecific">
+public Query createNamedQuery (String name);
+</programlisting>
+ <para>
+ This method retrieves a query defined in metadata by name. The returned
+ <classname>Query</classname> instance is initialized with the
+ information declared in metadata. For more information on named
+ queries, read <xref linkend="jpa_overview_query_named"/>.
+ </para>
+ <programlisting format="linespecific">
+public Query createNativeQuery (String sql);
+public Query createNativeQuery (String sql, Class resultCls);
+public Query createNativeQuery (String sql, String resultMapping);
+</programlisting>
+ <para><emphasis>Native</emphasis> queries are queries in the datastore's
+ native language. For relational databases, this the Structured Query
+ Language (SQL). <xref linkend="jpa_overview_sqlquery"/> elaborates
+ on EJB persistence's native query support.
+ </para>
+ </section>
+ <section id="jpa_overview_em_closing">
+ <title>Closing</title>
+ <indexterm zone="jpa_overview_em_closing">
+ <primary>EntityManager</primary>
+ <secondary>closing</secondary>
+ </indexterm>
+ <programlisting format="linespecific">
+public boolean isOpen ();
+public void close ();
+</programlisting>
+ <para>
+ When an <classname>EntityManager</classname> is no longer
+ needed, you should call its <methodname>close</methodname> method.
+ Closing an <classname>EntityManager</classname> releases any resources
+ it is using. The persistence context ends, and the entities managed by
+ the <classname>EntityManager</classname> become detached.
+ Any <classname>Query</classname> instances the <classname>EntityManager
+ </classname> created become invalid.
+ Calling any method other than <methodname>isOpen</methodname> on a
+ closed <classname>EntityManager</classname> results in an
+ <classname>IllegalStateException</classname>. You cannot close a
+ <classname>EntityManager</classname> that is in the middle of a
+ transaction.
+ </para>
+ <para>
+ If you are in a managed environment using injected entity managers,
+ you should not close them.
+ </para>
+ </section>
+ </chapter>
Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml Tue Aug 22 14:28:53 2006
@@ -0,0 +1,365 @@
+
+ <chapter id="jpa_overview_emfactory">
+ <title>EntityManagerFactory</title>
+ <indexterm zone="jpa_overview_emfactory">
+ <primary>EntityManagerFactory</primary>
+ </indexterm>
+ <mediaobject>
+ <imageobject>
+<!-- PNG image data, 418 x 274 (see README) -->
+ <imagedata fileref="img/entitymanagerfactory.png" width="279px"/>
+ </imageobject>
+ </mediaobject>
+ <para>
+ The <classname>EntityManagerFactory</classname> creates
+ <classname>EntityManager</classname> instances for application
+ use.
+ </para>
+ <note>
+ <para>
+ OpenJPA extends the standard <classname>EntityManagerFactory</classname>
+ interface with the
+ <ulink url="../../api/openjpa/persistence/OpenJPAEntityManagerFactory.html"><classname>OpenJPAEntityManagerFactory</classname></ulink> to provide
+ additional functionality.
+ </para>
+ </note>
+ <section id="jpa_overview_emfactory_obtain">
+ <title>Obtaining an EntityManagerFactory</title>
+ <indexterm zone="jpa_overview_emfactory_obtain">
+ <primary>EntityManagerFactory</primary>
+ <secondary>construction</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Java Connector Architecture</primary>
+ <see>JCA</see>
+ </indexterm>
+ <indexterm>
+ <primary>JCA</primary>
+ </indexterm>
+ <para>
+ Within a container, you will typically use <emphasis>injection
+ </emphasis> to access an <classname>EntityManagerFactory</classname>.
+ There are, however, alternative mechanisms for
+ <classname>EntityManagerFactory</classname> construction.
+ </para>
+ <para>
+ Some vendors may supply public constructors for their
+ <classname>EntityManagerFactory</classname> implementations, but
+ we recommend using the Java Connector Architecture (JCA) in a managed
+ environment, or the <classname>Persistence</classname> class'
+ <methodname>createEntityManagerFactory</methodname> methods in an
+ unmanaged environment, as described in
+ <xref linkend="jpa_overview_persistence"/>. These strategies allow
+ vendors to pool factories, cutting down on resource utilization.
+ </para>
+ <para><indexterm><primary>JNDI</primary></indexterm>
+ JPA allows you to create and configure an
+ <classname>EntityManagerFactory</classname>, then store it in a
+ Java Naming and Directory Interface (JNDI) tree for later retrieval
+ and use.
+ </para>
+ </section>
+ <section id="jpa_overview_emfactory_em">
+ <title>Obtaining EntityManagers</title>
+ <indexterm zone="jpa_overview_emfactory_em">
+ <primary>EntityManager</primary>
+ <secondary>obtaining</secondary>
+ <seealso>EntityManagerFactory</seealso>
+ </indexterm>
+ <indexterm zone="jpa_overview_emfactory_em">
+ <primary>EntityManagerFactory</primary>
+ <secondary>obtaining EntityManagers</secondary>
+ </indexterm>
+ <programlisting format="linespecific">
+public EntityManager createEntityManager ();
+public EntityManager createEntityManager (Map map);
+</programlisting>
+ <para>
+ The two <methodname>createEntityManager</methodname> methods above
+ create a new <classname>EntityManager</classname> each time they are
+ invoked. The optional <classname>Map</classname> is used to to supply
+ vendor-specific settings. If you have configured your implementation
+ for JTA transactions and a JTA transaction is active, the returned
+ <classname>EntityManager</classname> will be synchronized with that
+ transaction.
+ <!--
+ <classname>EntityManager</classname> with a persistence context type of
+ <literal>TRANSACTION</literal>. The second version allows you to
+ specify the persistence context type. We relate the differences
+ between persistence context types
+ <link linkend="jpa_overview_emfactory_perscontext">below</link>.
+ -->
+ </para>
+ <note>
+ <para>
+ OpenJPA recognizes the following string keys in the map supplied to
+ <methodname>createEntityManager</methodname>:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>openjpa.ConnectionUserName</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>openjpa.ConnectionPassword</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>openjpa.ConnectionRetainMode</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>openjpa.TransactionMode</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>openjpa.<property></literal>, where
+ <emphasis><property></emphasis> is any JavaBean
+ property of the
+ <ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html"><classname>
+ org.apache.openjpa.persistence.OpenJPAEntityManager</classname></ulink>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The last option uses reflection to configure any property of OpenJPA's
+ <classname>EntityManager</classname> implementation with the value
+ supplied in your map. The first options correspond exactly to
+ the same-named OpenJPA configuration keys described in
+ <xref linkend="ref_guide_conf"/> of the Reference Guide.
+ </para>
+ </note>
+ </section>
+ <section id="jpa_overview_emfactory_perscontext">
+ <title>Persistence Context</title>
+ <indexterm zone="jpa_overview_emfactory_perscontext">
+ <primary>persistence context</primary>
+ </indexterm>
+ <indexterm>
+ <primary>PersistenceContextType</primary>
+ <see>persistence context</see>
+ </indexterm>
+ <para>
+ A persistence context is a set of entities such that for any persistent
+ identity there is a unique entity instance. Within a persistence
+ context, entities are <emphasis>managed</emphasis>. The <classname>
+ EntityManager</classname> controls their lifecycle, and they can access
+ datastore resources.
+ </para>
+ <para>
+ When a persistence context ends, previously-managed entities become
+ <emphasis>detached</emphasis>. A detached entity is no longer under
+ the control of the <classname>EntityManager</classname>, and no longer
+ has access to datastore resources. We discuss detachment is detail in
+ <xref linkend="jpa_overview_em_lifecycle"/>. For now, it is sufficient
+ to know that detachment as has two obvious consequences:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The detached entity cannot load any additional persistent
+ state.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <classname>EntityManager</classname> will not return the
+ detached entity from <methodname>find</methodname>, nor will
+ queries include the detached entity in their results. Instead,
+ <methodname>find</methodname> method invocations and query
+ executions that would normally incorporate the detached entity
+ will create a new managed entity with the same identity.
+ </para>
+ </listitem>
+ </orderedlist>
+ <note>
+ <para>
+ OpenJPA offers several features related to detaching entities. See
+ <xref linkend="ref_guide_detach"/> in the Reference Guide.
+ <xref linkend="ref_guide_detach_graph"/> in particular describes
+ how to use the <literal>DetachState</literal> setting to boost
+ the performance of merging detached entities.
+ </para>
+ </note>
+ <para>
+ Injected <classname>EntityManager</classname>s have use a
+ <emphasis>transaction</emphasis>, while <classname>
+ EntityManager</classname>s obtained through the
+ <classname>EntityManagerFactory</classname> have an <emphasis>
+ extended</emphasis> persistence context. We describe these persistence
+ context types below.
+ </para>
+ <section id="jpa_overview_emfactory_perscontext_trans">
+ <title>Transaction Persistence Context</title>
+ <para>
+ Under the transaction persistence context model, an <classname>
+ EntityManager</classname> begins a new persistence context
+ with each transaction, and ends the context when the transaction
+ commits or rolls back. Within the transaction, entities you
+ retrieve through the <classname>EntityManager</classname> or via
+ <classname>Queries</classname> are managed entities. They
+ can access datastore resources to lazy-load additional
+ persistent state as needed, and only one entity may exist for any
+ persistent identity.
+ </para>
+ <para>
+ When the transaction completes, all entities lose their
+ association with the <classname>EntityManager</classname> and
+ become detached. Traversing a persistent field that wasn't
+ already loaded now has undefined results. And using the <classname>
+ EntityManager</classname> or a <classname>Query</classname> to
+ retrieve additional objects may now create new instances with the
+ same persistent identities as detached instances.
+ </para>
+ <para>
+ If you use an <classname>EntityManager</classname> with a
+ transaction persistence context model outside of
+ an active transaction, each method invocation creates a new
+ persistence context, performs the method action, and ends the
+ persistence context. For example, consider using the
+ <methodname>EntityManager.find</methodname> method outside
+ of a transaction. The <classname>EntityManager</classname> will
+ create a temporary persistence context, perform the find operation,
+ end the persistence context, and return the detached result object
+ to you. A second call with the same id will return a second
+ detached object.
+ </para>
+ <para>
+ When the next transaction begins, the <classname>EntityManager
+ </classname> will begin a new persistence context, and will again
+ start returning managed entities. As you'll see in
+ <xref linkend="jpa_overview_em"/>, you can also merge the
+ previously-detached entites back into the new persistence context.
+ </para>
+ <example id="jpa_overview_emfactory_perscontext_transex">
+ <title>Behavior of Transaction Persistence Context</title>
+ <para>
+ The following code illustrates the behavior of entites under
+ an <classname>EntityManager</classname> using a transaction
+ persistence context.
+ </para>
+ <programlisting format="linespecific">
+EntityManager em; // injected
+...
+
+// outside a transaction:
+
+// each operation occurs in a separate persistence context, and returns
+// a new detached instance
+Magazine mag1 = em.find (Magazine.class, magId);
+Magazine mag2 = em.find (Magazine.class, magId);
+assertTrue (mag2 != mag1);
+...
+
+// transaction begins:
+
+// within a transaction, a subsequent lookup doesn't return any of the
+// detached objects. however, two lookups within the same transaction
+// return the same instance, because the persistence context spans the
+// transaction
+Magazine mag3 = em.find (Magazine.class, magId);
+assertTrue (mag3 != mag1 && mag3 != mag2);
+Magazine mag4 = em.find (Magazine.class (magId);
+assertTrue (mag4 == mag3);
+...
+
+// transaction commits:
+
+// once again, each operation returns a new instance
+Magazine mag5 = em.find (Magazine.class, magId);
+assertTrue (mag5 != mag3);
+</programlisting>
+ </example>
+ </section>
+ <section id="jpa_overview_emfactory_perscontext_extend">
+ <title>Extended Persistence Context</title>
+ <para>
+ An <classname>EntityManager</classname> using an extended
+ persistence context maintains the same persistence context for
+ its entire lifecycle. Whether inside a transaction or not, all
+ entities returned from the <classname>EntityManager</classname>
+ are managed, and the <classname>EntityManager</classname> never
+ creates two entity instances to represent the same persistent
+ identity. Entities only become detached when you finally close
+ the <classname>EntityManager</classname> (or when they are
+ serialized).
+ </para>
+ <example id="jpa_overview_emfactory_perscontext_extendex">
+ <title>Behavior of Extended Persistence Context</title>
+ <para>
+ The following code illustrates the behavior of entites under
+ an <classname>EntityManager</classname> using an extended
+ persistence context.
+ </para>
+ <programlisting format="linespecific">
+EntityManagerFactory emf = ...
+EntityManager em = emf.createEntityManager (PersistenceContextType.EXTENDED);
+
+// persistence context active for entire life of EM, so only one entity
+// for a given persistent identity
+Magazine mag1 = em.find (Magazine.class, magId);
+Magazine mag2 = em.find (Magazine.class, magId);
+assertTrue (mag2 == mag1);
+
+em.getTransaction ().begin ();
+
+// same persistence context active within the transaction
+Magazine mag3 = em.find (Magazine.class, magId);
+assertTrue (mag3 == mag1);
+Magazine mag4 = em.find (Magazine.class (magId);
+assertTrue (mag4 == mag1);
+
+em.getTransaction.commit ();
+
+// when the transaction commits, instance still managed
+Magazine mag5 = em.find (Magazine.class, magId);
+assertTrue (mag5 == mag1);
+
+// instance finally becomes detached when EM closes
+em.close ();
+</programlisting>
+ </example>
+ </section>
+ </section>
+ <section id="jpa_overview_emfactory_close">
+ <title>Closing the EntityManagerFactory</title>
+ <indexterm zone="jpa_overview_emfactory_close">
+ <primary>EntityManagerFactory</primary>
+ <secondary>closing</secondary>
+ </indexterm>
+ <programlisting format="linespecific">
+public boolean isOpen ();
+public void close ();
+</programlisting>
+ <para><classname>EntityManagerFactory</classname> instances are
+ heavyweight objects. Each factory might maintain a metadata cache,
+ object state cache, <classname>EntityManager</classname> pool,
+ connection pool, and more. If your application no longer needs an
+ <classname>EntityManagerFactory</classname>, you should close it
+ to free these resources. When an <classname>EntityManagerFactory
+ </classname> closes, all <classname>EntityManager</classname>s
+ from that factory, and by extension all entities managed
+ by those <classname>EntityManager</classname>s, become invalid.
+ Attempting to close an <classname>EntityManagerFactory</classname>
+ while one or more of its <classname>EntityManager</classname>s
+ has an active transaction may result in an
+ <classname>IllegalStateException</classname>.
+ </para>
+ <para>
+ Closing an <classname>EntityManagerFactory</classname> should not
+ be taken lightly. It is much better to keep a factory open for a long
+ period of time than to repeatedly create and close new factories. Thus,
+ most applications will never close the factory, or only close it when
+ the application is exiting. Only applications that require multiple
+ factories with different configurations have an obvious reason to
+ create and close multiple <classname>EntityManagerFactory
+ </classname> instances. Once a factory is closed, all methods except
+ <methodname>isOpen</methodname> throw an <classname>
+ IllegalStateException</classname>.
+ </para>
+ </section>
+ </chapter>
Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_intro.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_intro.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_intro.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_intro.xml Tue Aug 22 14:28:53 2006
@@ -0,0 +1,57 @@
+
+ <chapter id="jpa_overview_intro">
+ <title>Introduction</title>
+ <para><indexterm><primary>EJB3 Persistence</primary><see>EJB</see></indexterm><indexterm><primary>EJB</primary></indexterm>
+ Enterprise Java Beans 3.0 Persistence (EJB persistence) is a specification
+ from Sun Microsystems for the persistence of Java objects to any relational
+ datastore. EJB persistence requires J2SE 1.5 (also referred to as "Java 5")
+ or higher, as it makes heavy use of new Java language features such as
+ annotations and generics. This document provides an overview of EJB
+ persistence. Unless otherwise noted, the information presented
+ applies to all EJB persistence implementations.
+ </para>
+ <note>
+ <para>
+ This document describes the Public Draft of the EJB 3.0
+ persistence specification.
+ </para>
+ <para>
+ For coverage of OpenJPA's many extensions to the EJB persistence
+ specification, see the <link linkend="ref_guide_intro">Reference
+ Guide</link>.
+ </para>
+ </note>
+ <section id="jpa_overview_intro_audience">
+ <title>Intended Audience</title>
+ <para>
+ This document is intended for developers who want to learn about
+ EJB persistence in order to use it in their applications.
+ It assumes that you have a strong knowledge of object-oriented concepts
+ and Java, including Java 5 annotations and generics. It also assumes
+ some experience with relational databases and the
+ Structured Query Language (SQL).
+ </para>
+ </section>
+ <section id="jpa_overview_intro_transpers">
+ <title>Lightweight Persistence</title>
+ <indexterm zone="jpa_overview_intro_transpers">
+ <primary>lightweight persistence</primary>
+ </indexterm>
+ <para><indexterm><primary>persistent data</primary></indexterm><emphasis>Persistent data</emphasis> is information that can
+ outlive the program that creates it. The majority of complex
+ programs use persistent data: GUI applications need to store user
+ preferences across program invocations, web applications track
+ user movements and orders over long periods of time, etc.
+ </para>
+ <para><emphasis>Lightweight persistence</emphasis> is the storage and
+ retrieval of persistent data with little or no work from you, the
+ developer. For example, Java serialization<indexterm><primary>serialization</primary></indexterm> is a form of
+ lightweight persistence because it can be used to persist Java
+ objects directly to a file with very little effort. Serialization's
+ capabilities as a lightweight persistence mechanism pale in
+ comparison to those provided by EJB, however. The next
+ chapter compares EJB to serialization and other available
+ persistence mechanisms.
+ </para>
+ </section>
+ </chapter>