openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From awh...@apache.org
Subject svn commit: r434517 [2/23] - in /incubator/openjpa/trunk: openjpa-kernel/src/main/java/org/apache/openjpa/meta/ openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/ openjpa-project/src/doc/manual/
Date Thu, 24 Aug 2006 20:41:14 GMT
Modified: 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=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_em.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_em.xml Thu Aug 24 13:41:12 2006
@@ -1,406 +1,566 @@
-
-    <chapter id="jpa_overview_em">
-      <title>EntityManager</title>
-      <indexterm zone="jpa_overview_em">
-        <primary>EntityManager</primary>
-      </indexterm>
-      <mediaobject>
+<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"/>
+            <!-- PNG image data, 283 x 391 (see README) -->
+            <imagedata fileref="img/entitymanager.png" width="189px">
+            </imagedata>
         </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.
+    </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 JPA runtime. The methods
+of the <classname>EntityManager</classname> can be divided into the following
+functional categories:
     </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>
+    <itemizedlist>
         <listitem>
-          <para><classname>Transaction</classname> association.</para>
+            <para>
+<classname>Transaction</classname> association.
+            </para>
         </listitem>
         <listitem>
-          <para>Entity lifecycle management.</para>
+            <para>
+Entity lifecycle management.
+            </para>
         </listitem>
         <listitem>
-          <para>Entity identity management.</para>
+            <para>
+Entity identity management.
+            </para>
         </listitem>
         <listitem>
-          <para>Cache management.</para>
+            <para>
+Cache management.
+            </para>
         </listitem>
         <listitem>
-          <para><classname>Query</classname> factory.</para>
+            <para>
+<classname>Query</classname> factory.
+            </para>
         </listitem>
         <listitem>
-          <para>Closing.</para>
+            <para>
+Closing.
+            </para>
         </listitem>
-      </itemizedlist>
-      <section id="jpa_overview_em_trans">
-        <title>Transaction Association</title>
+    </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>
+            <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>
+            <primary>
+                Transaction
+            </primary>
+            <secondary>
+                obtaining from EntityManager
+            </secondary>
         </indexterm>
-        <programlisting format="linespecific">
+<programlisting>
 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>
+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 JPA 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>
+            <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">
+        <para>
+<classname>EntityManager</classname>s perform several actions that affect the
+lifecycle state of entity instances.
+        </para>
+<programlisting>
 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.
+        <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>
-          </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>
+For a given entity <literal>A</literal>, the <methodname>persist</methodname>
+method behaves as follows:
         </para>
-          </listitem>
+        <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">
+This action can only be used in the context of an active transaction.
+        </para>
+<programlisting>
 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.
+        <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>
-          </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>
+For a given entity <literal>A</literal>, the <methodname>remove</methodname>
+method behaves as follows:
         </para>
-          </listitem>
+        <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">
+This action can only be used in the context of an active transaction.
+        </para>
+<programlisting>
 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.
+        <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>
-          </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>
+For a given entity <literal>A</literal>, the <methodname>refresh</methodname>
+method behaves as follows:
         </para>
-          </listitem>
+        <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">
+<programlisting>
 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>
+        <indexterm>
+            <primary>
+                EntityManager
+            </primary>
+            <secondary>
+                merge
+            </secondary>
+            <seealso>
+                detachment
+            </seealso>
+        </indexterm>
+        <indexterm>
+            <primary>
+                detachment
+            </primary>
+            <secondary>
+                JPA
+            </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>
+JPA 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"></xref> for an exploration of
+persistence contexts). The JPA <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>
+            <para>
+OpenJPA offers enhancements to JPA detachment functionality,
+including additional options to control which fields are detached. See
+<xref linkend="ref_guide_detach"></xref> 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.
+For a given entity <literal>A</literal>, the <methodname>merge</methodname>
+method behaves as follows:
         </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>
+            <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">
+<programlisting>
 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>
+        <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>
-          </listitem>
+        <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>
+            <para>
+OpenJPA has additional APIs for controlling object locking. See
+<xref linkend="ref_guide_locking"></xref> 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>
+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>
+            <imageobject>
+                <!-- PNG image data, 445 x 337 (see README) -->
+                <imagedata fileref="img/jpa-state-transitions.png" width="297px">
+                </imagedata>
+            </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>
+    </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">
+            <title>
+                Persisting Objects
+            </title>
+            <indexterm>
+                <primary>
+                    persistent objects
+                </primary>
+                <secondary>
+                    persisting
+                </secondary>
+                <tertiary>
+                    example
+                </tertiary>
+            </indexterm>
+<programlisting>
 // create some objects
 Magazine mag = new Magazine ("1B78-YU9L", "JavaWorld");
 
@@ -409,7 +569,7 @@
 mag.setPublisher (pub);
 pub.addMagazine (mag);
 
-Article art = new Article ("EJB Rules!", "Transparent Object Persistence");
+Article art = new Article ("JPA Rules!", "Transparent Object Persistence");
 art.addAuthor (new Author ("Fred", "Hoyle"));
 mag.addArticle (art);
 
@@ -426,20 +586,28 @@
 </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">
+            <title>
+                Updating Objects
+            </title>
+            <indexterm>
+                <primary>
+                    persistent objects
+                </primary>
+                <secondary>
+                    updating
+                </secondary>
+                <tertiary>
+                    example
+                </tertiary>
+            </indexterm>
+<programlisting>
 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
+// with the transaction; JPA automatically tracks all changes
 EntityManager em = emf.createEntityManager ();
 em.getTransaction ().begin ();
 Magazine mag = em.find (Magazine.class, mi);
@@ -453,13 +621,21 @@
 </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">
+            <title>
+                Removing Objects
+            </title>
+            <indexterm>
+                <primary>
+                    persistent objects
+                </primary>
+                <secondary>
+                    deleting
+                </secondary>
+                <tertiary>
+                    example
+                </tertiary>
+            </indexterm>
+<programlisting>
 // assume we have an object id for the company whose subscriptions
 // we want to delete
 Object oid = ...;
@@ -478,13 +654,15 @@
 </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">
+            <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>
 // CLIENT:
 // requests an object with a given oid
 Record detached = (Record) getFromServer (oid);
@@ -520,195 +698,344 @@
 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">
+    </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"></xref> for an explanation of
+persistence contexts.
+        </para>
+<programlisting>
 public &lt;T&gt; T find (Class&lt;T&gt; 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">
+        <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>
 public &lt;T&gt; T getReference (Class&lt;T&gt; 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">
+        <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>
 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>
+        <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>
+            <primary>
+                EntityManager
+            </primary>
+            <secondary>
+                cache
+            </secondary>
         </indexterm>
-        <programlisting format="linespecific">
+<programlisting>
 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">
+        <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"></xref>.
+        </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>
 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>
+        <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>
-          </listitem>
+        <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>
+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>
+            <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"></xref>.
+            </para>
         </note>
-        <programlisting format="linespecific">
+<programlisting>
 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>
+        <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>
+            <primary>
+                EntityManager
+            </primary>
+            <secondary>
+                as Query factory
+            </secondary>
+            <seealso>
+                Query
+            </seealso>
         </indexterm>
         <indexterm zone="jpa_overview_em_query">
-          <primary>Query</primary>
-          <secondary>creating</secondary>
+            <primary>
+                Query
+            </primary>
+            <secondary>
+                creating
+            </secondary>
         </indexterm>
-        <programlisting format="linespecific">
+<programlisting>
 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">
+        <para>
+<classname>Query</classname> objects are used to find entities matching certain
+criteria. The <methodname>createQuery</methodname> method creates a query using
+the given Java Persistence Query Language (JPQL) string. See
+<xref linkend="jpa_overview_query"></xref> for details.
+        </para>
+<programlisting>
 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">
+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"></xref>.
+        </para>
+<programlisting>
 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>
+        <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"></xref> elaborates on JPA'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>
+            <primary>
+                EntityManager
+            </primary>
+            <secondary>
+                closing
+            </secondary>
         </indexterm>
-        <programlisting format="linespecific">
+<programlisting>
 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>
+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>
+If you are in a managed environment using injected entity managers, you should
+not close them.
+        </para>
+    </section>
+</chapter>

Modified: 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=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml Thu Aug 24 13:41:12 2006
@@ -1,248 +1,274 @@
-
-    <chapter id="jpa_overview_emfactory">
-      <title>EntityManagerFactory</title>
-      <indexterm zone="jpa_overview_emfactory">
-        <primary>EntityManagerFactory</primary>
-      </indexterm>
-      <mediaobject>
+<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"/>
+            <!-- PNG image data, 418 x 274 (see README) -->
+            <imagedata fileref="img/entitymanagerfactory.png" width="279px">
+            </imagedata>
         </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.
+    </mediaobject>
+    <para>
+The <classname>EntityManagerFactory</classname> creates <classname>
+EntityManager</classname> instances for application use.
     </para>
-      </note>
-      <section id="jpa_overview_emfactory_obtain">
-        <title>Obtaining an EntityManagerFactory</title>
+    <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>
+            <primary>
+                EntityManagerFactory
+            </primary>
+            <secondary>
+                construction
+            </secondary>
         </indexterm>
         <indexterm>
-          <primary>Java Connector Architecture</primary>
-          <see>JCA</see>
+            <primary>
+                Java Connector Architecture
+            </primary>
+            <see>
+                JCA
+            </see>
         </indexterm>
         <indexterm>
-          <primary>JCA</primary>
+            <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>
+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>
+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"></xref>. 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>
+            <primary>
+                EntityManager
+            </primary>
+            <secondary>
+                obtaining
+            </secondary>
+            <seealso>
+                EntityManagerFactory
+            </seealso>
         </indexterm>
         <indexterm zone="jpa_overview_emfactory_em">
-          <primary>EntityManagerFactory</primary>
-          <secondary>obtaining EntityManagers</secondary>
+            <primary>
+                EntityManagerFactory
+            </primary>
+            <secondary>
+                obtaining EntityManagers
+            </secondary>
         </indexterm>
-        <programlisting format="linespecific">
+<programlisting>
 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>
+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.
+        </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.&lt;property&gt;</literal>, where 
-          <emphasis>&lt;property&gt;</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>
+            <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.&lt;property&gt;</literal>, where <emphasis>&lt;property&gt;
+</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"></xref> of the
+Reference Guide.
+            </para>
         </note>
-      </section>
-      <section id="jpa_overview_emfactory_perscontext">
-        <title>Persistence Context</title>
+    </section>
+    <section id="jpa_overview_emfactory_perscontext">
+        <title>
+            Persistence Context
+        </title>
         <indexterm zone="jpa_overview_emfactory_perscontext">
-          <primary>persistence context</primary>
+            <primary>
+                persistence context
+            </primary>
         </indexterm>
         <indexterm>
-          <primary>PersistenceContextType</primary>
-          <see>persistence context</see>
+            <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.
+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>
-          </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>
+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"></xref>. For now, it is sufficient to
+know that detachment as has two obvious consequences:
         </para>
-          </listitem>
+        <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>
+            <para>
+OpenJPA offers several features related to detaching entities. See
+<xref linkend="ref_guide_detach"></xref> in the Reference Guide.
+<xref linkend="ref_guide_detach_graph"></xref> 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>
+        <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>
+            <title>
+                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">
+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"></xref>, 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>
 EntityManager em; // injected
 ...
 
@@ -273,29 +299,30 @@
 Magazine mag5 = em.find (Magazine.class, magId);
 assertTrue (mag5 != mag3);
 </programlisting>
-          </example>
+            </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>
+            <title>
+                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">
+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>
 EntityManagerFactory emf = ...
 EntityManager em = emf.createEntityManager (PersistenceContextType.EXTENDED);
 
@@ -322,44 +349,48 @@
 // instance finally becomes detached when EM closes
 em.close ();
 </programlisting>
-          </example>
+            </example>
         </section>
-      </section>
-      <section id="jpa_overview_emfactory_close">
-        <title>Closing the EntityManagerFactory</title>
+    </section>
+    <section id="jpa_overview_emfactory_close">
+        <title>
+            Closing the EntityManagerFactory
+        </title>
         <indexterm zone="jpa_overview_emfactory_close">
-          <primary>EntityManagerFactory</primary>
-          <secondary>closing</secondary>
+            <primary>
+                EntityManagerFactory
+            </primary>
+            <secondary>
+                closing
+            </secondary>
         </indexterm>
-        <programlisting format="linespecific">
+<programlisting>
 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>
+<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>



Mime
View raw message