You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by aw...@apache.org on 2006/08/24 22:41:14 UTC
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/
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 <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">
+ <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 <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">
+ <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.<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>
+ <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"></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>