| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>2. Entity Lifecycle Management</title><link rel="stylesheet" href="css/docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><link rel="start" href="manual.html" title="Apache OpenJPA User's Guide"><link rel="up" href="jpa_overview_em.html" title="Chapter 8. EntityManager"><link rel="prev" href="jpa_overview_em.html" title="Chapter 8. EntityManager"><link rel="next" href="jpa_overview_em_lifeexamples.html" title="3. Lifecycle Examples"></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">2. |
| Entity Lifecycle Management |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_em.html">Prev</a> </td><th width="60%" align="center">Chapter 8. |
| EntityManager |
| </th><td width="20%" align="right"> <a accesskey="n" href="jpa_overview_em_lifeexamples.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_em_lifecycle"></a>2. |
| Entity Lifecycle Management |
| </h2></div></div></div><a class="indexterm" name="d0e4574"></a><p> |
| <code class="classname">EntityManager</code>s perform several actions that affect the |
| lifecycle state of entity instances. |
| </p><pre class="programlisting"> |
| public void persist(Object entity); |
| </pre><p> |
| <a class="indexterm" name="d0e4588"></a> |
| <a class="indexterm" name="d0e4594"></a> |
| <a class="indexterm" name="d0e4600"></a> |
| Transitions new instances to managed. On the next flush or commit, the newly |
| persisted instances will be inserted into the datastore. |
| </p><p> |
| For a given entity <code class="literal">A</code>, the <code class="methodname">persist</code> |
| method behaves as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| If <code class="literal">A</code> is a new entity, it becomes managed. |
| </p></li><li><p> |
| If <code class="literal">A</code> is an existing managed entity, it is ignored. However, |
| the persist operation cascades as defined below. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a removed entity, it becomes managed. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a detached entity, an <code class="classname"> |
| IllegalArgumentException</code> is thrown. |
| </p></li><li><p> |
| The persist operation recurses on all relation fields of <code class="literal">A</code> |
| whose <a href="jpa_overview_meta_field.html#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">cascades</a> include |
| <code class="literal">CascadeType.PERSIST</code>. |
| </p></li></ul></div><p> |
| This action can only be used in the context of an active transaction. |
| </p><pre class="programlisting"> |
| public void remove(Object entity); |
| </pre><p> |
| <a class="indexterm" name="d0e4660"></a> |
| <a class="indexterm" name="d0e4666"></a> |
| <a class="indexterm" name="d0e4672"></a> |
| 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. |
| </p><p> |
| For a given entity <code class="literal">A</code>, the <code class="methodname">remove</code> |
| method behaves as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| If <code class="literal">A</code> is a new entity, it is ignored. However, the remove |
| operation cascades as defined below. |
| </p></li><li><p> |
| If <code class="literal">A</code> is an existing managed entity, it becomes removed. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a removed entity, it is ignored. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a detached entity, an <code class="classname"> |
| IllegalArgumentException</code> is thrown. |
| </p></li><li><p> |
| The remove operation recurses on all relation fields of <code class="literal">A</code> |
| whose <a href="jpa_overview_meta_field.html#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">cascades</a> include |
| <code class="literal">CascadeType.REMOVE</code>. |
| </p></li></ul></div><p> |
| This action can only be used in the context of an active transaction. |
| </p><pre class="programlisting"> |
| public void refresh(Object entity); |
| </pre><p> |
| <a class="indexterm" name="d0e4732"></a> |
| <a class="indexterm" name="d0e4738"></a> |
| <a class="indexterm" name="d0e4744"></a> |
| <a class="indexterm" name="d0e4750"></a> |
| Use the <code class="methodname">refresh</code> action to make sure the persistent |
| state of an instance is synchronized with the values in the datastore. |
| <code class="methodname">refresh</code> is intended for long-running optimistic |
| transactions in which there is a danger of seeing stale data. |
| </p><p> |
| For a given entity <code class="literal">A</code>, the <code class="methodname">refresh</code> |
| method behaves as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| If <code class="literal">A</code> is a new entity, it is ignored. However, the refresh |
| operation cascades as defined below. |
| </p></li><li><p> |
| If <code class="literal">A</code> is an existing managed entity, its state is refreshed |
| from the datastore. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a removed entity, it is ignored. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a detached entity, an <code class="classname"> |
| IllegalArgumentException</code> is thrown. |
| </p></li><li><p> |
| The refresh operation recurses on all relation fields of <code class="literal">A</code> |
| whose <a href="jpa_overview_meta_field.html#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">cascades</a> include |
| <code class="literal">CascadeType.REFRESH</code>. |
| </p></li></ul></div><pre class="programlisting"> |
| public Object merge(Object entity); |
| </pre><p> |
| <a class="indexterm" name="d0e4814"></a> |
| <a class="indexterm" name="d0e4822"></a> |
| <a class="indexterm" name="d0e4828"></a> |
| <a class="indexterm" name="d0e4834"></a> |
| <a class="indexterm" name="d0e4838"></a> |
| 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 <span class="emphasis"><em>data transfer object</em></span> or <span class="emphasis"><em>value |
| object</em></span> pattern, and it allows fine-grained manipulation of data |
| objects without incurring the overhead of multiple remote method invocations. |
| </p><p> |
| JPA provides support for this pattern by automatically detaching |
| entities when they are serialized or when a persistence context ends (see |
| <a href="jpa_overview_emfactory_perscontext.html" title="3. Persistence Context">Section 3, “ |
| Persistence Context |
| ”</a> for an exploration of |
| persistence contexts). The JPA <span class="emphasis"><em>merge</em></span> 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 |
| <code class="classname">EntityManager</code> (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. |
| </p><p> |
| 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. |
| </p><p> |
| The <code class="methodname">merge</code> 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. |
| </p><p> |
| 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. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA offers enhancements to JPA detachment functionality, |
| including additional options to control which fields are detached. See |
| <a href="ref_guide_remote.html#ref_guide_detach" title="1. Detach and Attach">Section 1, “ |
| Detach and Attach |
| ”</a> in the Reference Guide for details. |
| </p></div><p> |
| For a given entity <code class="literal">A</code>, the <code class="methodname">merge</code> |
| method behaves as follows: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| If <code class="literal">A</code> is a detached entity, its state is copied into existing |
| managed instance <code class="literal">A'</code> of the same entity identity, or a new |
| managed copy of <code class="literal">A</code> is created. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a new entity, a new managed entity <code class="literal">A' |
| </code> is created and the state of <code class="literal">A</code> is copied into |
| <code class="literal">A'</code>. |
| </p></li><li><p> |
| If <code class="literal">A</code> is an existing managed entity, it is ignored. However, |
| the merge operation still cascades as defined below. |
| </p></li><li><p> |
| If <code class="literal">A</code> is a removed entity, an <code class="classname"> |
| IllegalArgumentException</code> is thrown. |
| </p></li><li><p> |
| The merge operation recurses on all relation fields of <code class="literal">A</code> |
| whose <a href="jpa_overview_meta_field.html#jpa_overview_meta_cascade" title="2.8.1. Cascade Type">cascades</a> include |
| <code class="literal">CascadeType.MERGE</code>. |
| </p></li></ul></div><pre class="programlisting"> |
| public void lock (Object entity, LockModeType mode); |
| </pre><p> |
| <a class="indexterm" name="d0e4939"></a> |
| <a class="indexterm" name="d0e4945"></a> |
| This method locks the given entity using the named mode. The |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/LockmodeType.html" target="_top"> |
| <code class="classname">javax.persistence.LockModeType</code></a> enum defines two |
| modes: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">READ</code>: Other transactions may concurrently read the object, |
| but cannot concurrently update it. |
| </p></li><li><p> |
| <code class="literal">WRITE</code>: 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. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA has additional APIs for controlling object locking. See |
| <a href="ref_guide_locking.html" title="3. Object Locking">Section 3, “ |
| Object Locking |
| ”</a> in the Reference Guide for details. |
| </p></div><p> |
| The following diagram illustrates the lifecycle of an entity with respect to the |
| APIs presented in this section. |
| </p><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="297"><tr><td><img src="img/jpa-state-transitions.png"></td></tr></table></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jpa_overview_em.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jpa_overview_em.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jpa_overview_em_lifeexamples.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 8. |
| EntityManager |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 3. |
| Lifecycle Examples |
| </td></tr></table></div></body></html> |
