| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>3. Persistence Context</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="jpa_overview_emfactory.html" title="Chapter 7. EntityManagerFactory"><link rel="prev" href="jpa_overview_emfactory_em.html" title="2. Obtaining EntityManagers"><link rel="next" href="jpa_overview_emf_properties.html" title="4. Retrieving Properties Information"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3. |
| Persistence Context |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_emfactory_em.html">Prev</a> </td><th width="60%" align="center">Chapter 7. |
| EntityManagerFactory |
| </th><td width="20%" align="right"> <a accesskey="n" href="jpa_overview_emf_properties.html">Next</a></td></tr></table><hr></div><div class="section" title="3. Persistence Context"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_emfactory_perscontext">3. |
| Persistence Context |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="jpa_overview_emfactory_perscontext.html#jpa_overview_emfactory_perscontext_trans">3.1. |
| Transaction Persistence Context |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_emfactory_perscontext.html#jpa_overview_emfactory_perscontext_extend">3.2. |
| Extended Persistence Context |
| </a></span></dt></dl></div> |
| |
| <a class="indexterm" name="d5e2184"></a> |
| <a class="indexterm" name="d5e2186"></a> |
| <p> |
| 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 |
| <span class="emphasis"><em>managed</em></span>. The <code class="classname"> EntityManager</code> controls |
| their lifecycle, and they can access datastore resources. |
| </p> |
| <p> |
| When a persistence context ends, previously-managed entities become <span class="emphasis"><em> |
| detached</em></span>. A detached entity is no longer under the control of the |
| <code class="classname">EntityManager</code>, and no longer has access to datastore |
| resources. We discuss detachment in detail in |
| <a class="xref" href="jpa_overview_em_lifecycle.html" title="2. Entity Lifecycle Management">Section 2, “ |
| Entity Lifecycle Management |
| ”</a>. For now, it is sufficient to |
| know that detachment has two obvious consequences: |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> |
| <p> |
| The detached entity cannot load any additional persistent state. |
| </p> |
| </li><li class="listitem"> |
| <p> |
| The <code class="classname">EntityManager</code> will not return the detached entity |
| from <code class="methodname">find</code>, nor will queries include the detached |
| entity in their results. Instead, <code class="methodname">find</code> method |
| invocations and query executions that would normally incorporate the detached |
| entity will create a new managed entity with the same identity. |
| </p> |
| </li></ol></div> |
| <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> |
| <p> |
| OpenJPA offers several features related to detaching entities. See |
| <a class="xref" href="ref_guide_remote.html#ref_guide_detach" title="1. Detach and Attach">Section 1, “ |
| Detach and Attach |
| ”</a> in the Reference Guide. |
| <a class="xref" href="ref_guide_remote.html#ref_guide_detach_graph" title="1.3. Defining the Detached Object Graph">Section 1.3, “ |
| Defining the Detached Object Graph |
| ”</a> in particular describes how to |
| use the <code class="literal">DetachState</code> setting to boost the performance of |
| merging detached entities. |
| </p> |
| </div> |
| <p> |
| Injected <code class="classname">EntityManager</code>s have a <span class="emphasis"><em>transaction |
| </em></span> persistence context, |
| while <code class="classname"> EntityManager</code>s obtained through the |
| <code class="classname">EntityManagerFactory</code> have an <span class="emphasis"><em>extended |
| </em></span> persistence context. We describe these persistence context types |
| below. |
| </p> |
| <div class="section" title="3.1. Transaction Persistence Context"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_emfactory_perscontext_trans">3.1. |
| Transaction Persistence Context |
| </h3></div></div></div> |
| |
| <p> |
| Under the transaction persistence context model, an <code class="classname"> EntityManager |
| </code> 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 <code class="classname">EntityManager</code> or via |
| <code class="classname">Queries</code> 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. |
| </p> |
| <p> |
| When the transaction completes, all entities lose their association with the |
| <code class="classname">EntityManager</code> and become detached. Traversing a |
| persistent field that wasn't already loaded now has undefined results. And using |
| the <code class="classname"> EntityManager</code> or a <code class="classname">Query</code> to |
| retrieve additional objects may now create new instances with the same |
| persistent identities as detached instances. |
| </p> |
| <p> |
| If you use an <code class="classname">EntityManager</code> 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 <code class="methodname"> |
| EntityManager.find</code> method outside of a transaction. The <code class="classname"> |
| EntityManager</code> 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. |
| </p> |
| <p> |
| When the next transaction begins, the <code class="classname">EntityManager</code> will |
| begin a new persistence context, and will again start returning managed |
| entities. As you'll see in <a class="xref" href="jpa_overview_em.html" title="Chapter 8. EntityManager">Chapter 8, <i> |
| EntityManager |
| </i></a>, you can |
| also merge the previously-detached entities back into the new persistence |
| context. |
| </p> |
| <div class="example"><a name="jpa_overview_emfactory_perscontext_transex"></a><p class="title"><b>Example 7.1. |
| Behavior of Transaction Persistence Context |
| </b></p><div class="example-contents"> |
| |
| <p> |
| The following code illustrates the behavior of entities under an <code class="classname"> |
| EntityManager</code> using a transaction persistence context. |
| </p> |
| <pre class="programlisting"> |
| EntityManager em; // injected |
| ... |
| |
| // outside a transaction: |
| |
| // each operation occurs in a separate persistence context, and returns |
| // a new detached instance |
| Magazine mag1 = em.find(Magazine.class, magId); |
| Magazine mag2 = em.find(Magazine.class, magId); |
| assertTrue(mag2 != mag1); |
| ... |
| |
| // transaction begins: |
| |
| // within a transaction, a subsequent lookup doesn't return any of the |
| // detached objects. however, two lookups within the same transaction |
| // return the same instance, because the persistence context spans the |
| // transaction |
| Magazine mag3 = em.find(Magazine.class, magId); |
| assertTrue(mag3 != mag1 && mag3 != mag2); |
| Magazine mag4 = em.find(Magazine.class, magId); |
| assertTrue(mag4 == mag3); |
| ... |
| |
| // transaction commits: |
| |
| // once again, each operation returns a new instance |
| Magazine mag5 = em.find(Magazine.class, magId); |
| assertTrue(mag5 != mag3); |
| </pre> |
| </div></div><br class="example-break"> |
| </div> |
| <div class="section" title="3.2. Extended Persistence Context"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_emfactory_perscontext_extend">3.2. |
| Extended Persistence Context |
| </h3></div></div></div> |
| |
| <p> |
| An <code class="classname">EntityManager</code> 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 <code class="classname">EntityManager |
| </code> are managed, and the <code class="classname">EntityManager</code> never |
| creates two entity instances to represent the same persistent identity. Entities |
| only become detached when you finally close the <code class="classname">EntityManager |
| </code> (or when they are serialized). |
| </p> |
| <div class="example"><a name="jpa_overview_emfactory_perscontext_extendex"></a><p class="title"><b>Example 7.2. |
| Behavior of Extended Persistence Context |
| </b></p><div class="example-contents"> |
| |
| <p> |
| The following code illustrates the behavior of entities under an <code class="classname"> |
| EntityManager</code> using an extended persistence context. |
| </p> |
| <pre class="programlisting"> |
| EntityManagerFactory emf = ... |
| EntityManager em = emf.createEntityManager(); |
| |
| // persistence context active for entire life of EM, so only one entity |
| // for a given persistent identity |
| Magazine mag1 = em.find(Magazine.class, magId); |
| Magazine mag2 = em.find(Magazine.class, magId); |
| assertTrue(mag2 == mag1); |
| |
| em.getTransaction().begin(); |
| |
| // same persistence context active within the transaction |
| Magazine mag3 = em.find(Magazine.class, magId); |
| assertTrue(mag3 == mag1); |
| Magazine mag4 = em.find(Magazine.class, magId); |
| assertTrue(mag4 == mag1); |
| |
| em.getTransaction.commit(); |
| |
| // when the transaction commits, instance still managed |
| Magazine mag5 = em.find(Magazine.class, magId); |
| assertTrue(mag5 == mag1); |
| |
| // instance finally becomes detached when EM closes |
| em.close(); |
| </pre> |
| </div></div><br class="example-break"> |
| </div> |
| </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jpa_overview_emfactory_em.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jpa_overview_emfactory.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jpa_overview_emf_properties.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2. |
| Obtaining EntityManagers |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 4. |
| Retrieving Properties Information |
| </td></tr></table></div></body></html> |
