Return-Path: 
 <commits-return-4228-apmail-openjpa-commits-archive=openjpa.apache.org@openjpa.apache.org>
Delivered-To: apmail-openjpa-commits-archive@www.apache.org
Received: (qmail 85564 invoked from network); 6 May 2009 03:03:40 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3)
  by minotaur.apache.org with SMTP; 6 May 2009 03:03:40 -0000
Received: (qmail 19665 invoked by uid 500); 6 May 2009 03:03:39 -0000
Delivered-To: apmail-openjpa-commits-archive@openjpa.apache.org
Received: (qmail 19600 invoked by uid 500); 6 May 2009 03:03:39 -0000
Mailing-List: contact commits-help@openjpa.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@openjpa.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@openjpa.apache.org>
List-Post: <mailto:commits@openjpa.apache.org>
List-Id: <commits.openjpa.apache.org>
Reply-To: dev@openjpa.apache.org
Delivered-To: mailing list commits@openjpa.apache.org
Received: (qmail 19591 invoked by uid 99); 6 May 2009 03:03:39 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 06 May 2009 03:03:39 +0000
X-ASF-Spam-Status: No, hits=-2000.0 required=10.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 06 May 2009 03:03:37 +0000
Received: by eris.apache.org (Postfix, from userid 65534)
	id 300222388A16; Wed,  6 May 2009 03:03:17 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r772035 - in
 /openjpa/trunk/openjpa-project/src/doc/manual:
 migration_considerations.xml ref_guide_remote.xml
Date: Wed, 06 May 2009 03:03:16 -0000
To: commits@openjpa.apache.org
From: jrbauer@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20090506030317.300222388A16@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

Author: jrbauer
Date: Wed May  6 03:03:16 2009
New Revision: 772035

URL: http://svn.apache.org/viewvc?rev=772035&view=rev
Log:
OPENJPA-1027 Committing documentation updates contributed by Dianne Richards

Modified:
    openjpa/trunk/openjpa-project/src/doc/manual/migration_considerations.xml
    openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml

Modified: openjpa/trunk/openjpa-project/src/doc/manual/migration_considerations.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/migration_considerations.xml?rev=772035&r1=772034&r2=772035&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/migration_considerations.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/migration_considerations.xml Wed May  6 03:03:16 2009
@@ -30,21 +30,83 @@
     			Incompatibilities
     		</title>
     		<para>
-    		The following list indicates changes that are incompatible between
+    		The following sections indicate changes that are incompatible between
     		OpenJPA 1.x.x releases and the 2.0 release. Some of these may
     		require application changes.
-    			<orderedlist>
-    				<listitem>
-    					<para>
+    		</para>
+    		<section id="getProperties">
+    			<title>
+    				getProperties()
+    			</title>
+    			<para>
     					The OpenJPAEntityManagerFactory interface getProperties()
     					method was changed to return a Map instead of a
     					Properties object. This change was made in order to
     					support the getProperties() method defined in the 2.0
     					JPA specification.
     					</para>
-    				</listitem>
-    			</orderedlist>
-    		</para>
+    		</section>
+    		<section id="migration_detach_behavior">
+    			<title>
+    				Detach Behavior
+    			</title>
+    			<para>
+    			The detach behavior has changed in several ways:
+					<itemizedlist>
+						<listitem>
+							<para>
+							In the 1.x.x release, managed entities
+							were flushed to the database as part of the
+							detach operation. This is no longer done in
+							2.0.
+							</para>
+						</listitem>
+						<listitem>
+							<para>
+							In the 1.x.x release, entities were copied
+							and returned. In 2.0, for those methods
+							that have return values, the original
+							entities are returned.
+							</para>
+						</listitem>
+						<listitem>
+							<para>
+							In the 1.x.x release, managed entities still
+							exist in the persistent context. In 2.0,
+							they are removed.
+							</para>
+						</listitem>
+						<listitem>
+							<para>
+							In the 1.x.x release, the detach operation
+							is recursively cascaded to all referenced
+							entities. In 2.0, the detach operation is
+							only cascade to those entities for which
+							Cascade=detach has been specified.
+							</para>
+						</listitem>
+					</itemizedlist>
+    			</para>
+    			<para>
+    				It is possible to revert back to the 1.x.x behavior for
+    				some of these items by setting the openjpa.Compatibility
+    				property as follows:
+    				<simplelist>
+    					<member>CopyOnDetach=true</member>
+    					<member>FlushBeforeDetach=true</member>
+    					<member>CascadeWithDetach=true</member>
+    				</simplelist>
+    			</para>
+    			<para>
+    				In addition, a new method has been provided on the
+    				<ulink url="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
+					<classname>OpenJPAEntityManager</classname></ulink>
+    				interface to return a copy of the entity:
+    				<programlisting>
+					public &lt;T&gt; T detachCopy(T pc):
+					</programlisting>
+				</para>
+    		</section>
     	</section>
     </section>
 </appendix>

Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml?rev=772035&r1=772034&r2=772035&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml Wed May  6 03:03:16 2009
@@ -35,7 +35,8 @@
         </see>
     </indexterm>
     <para>
-The standard JPA runtime environment is <emphasis>local</emphasis> and
+The standard JPA runtime environment was originally just 
+<emphasis>local</emphasis> and 
 <emphasis>online</emphasis>. It is <emphasis>local</emphasis> in that components
 such as <classname>EntityManager</classname>s and queries connect directly to
 the datastore and execute their actions in the same JVM as the code using them.
@@ -43,13 +44,16 @@
 made in the context of an active <classname> EntityManager</classname>. These
 two properties, combined with the fact that <classname>
 EntityManager</classname>s cannot be serialized for storage or network transfer,
-make the standard JPA runtime difficult to incorporate into some enterprise and
+made the standard JPA runtime difficult to incorporate into some enterprise and
 client/server program designs.
     </para>
     <para>
-OpenJPA extends the standard runtime to add <emphasis>remote</emphasis> and
-<emphasis>offline</emphasis> capabilities in the form of enhanced
-<link linkend="ref_guide_detach">Detach and Attach APIs</link> and
+JPA has now provided <emphasis>offline</emphasis> capability through the 
+detach() and merge() methods on the EntityManager interface. OpenJPA has
+extended this to include additional detach...() and merge...() methods. All of
+these are documented in 
+<link linkend="ref_guide_detach">Detach and Attach APIs</link>. In addition,
+OpenJPA has added <emphasis>remote</emphasis> capability in the form of
 <link linkend="ref_guide_event">Remote Commit Events</link>. The following
 sections explain these capabilities in detail.
     </para>
@@ -87,80 +91,51 @@
                     behavior
                 </secondary>
             </indexterm>
+<note>
+<para>
+In version 2.0, the detach behavior has changed from the previous
+version. See the migration section
+<link linkend="migration_detach_behavior">Detach Behavior</link> for details.
+</para>
+</note>
             <para>
 In JPA, objects detach automatically when they are serialized or when a
 <link linkend="jpa_overview_emfactory_perscontext">persistence context</link>
-ends. The specification does not define any way to explicitly detach objects.
-The extended
+ends. The specification also allows objects to be explicitly detached using
+the following javax.persistence.EntityManager method:
+</para>
+<programlisting>
+public void detach(Object)
+</programlisting>
+			<para>
 <ulink url="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
-<classname>OpenJPAEntityManager</classname></ulink>, however, allows you to
-explicitly detach objects at any time.
+<classname>OpenJPAEntityManager</classname></ulink>, however, provides
+additional detach methods.
             </para>
 <programlisting>
-public Object detach(Object pc):
+public &lt;T&gt; T detachCopy(T pc):
 public Object[] detachAll(Object... pcs):
 public Collection detachAll(Collection pcs):
 </programlisting>
-            <para>
-Each detach method returns detached copies of the given instances. The copy
-mechanism is similar to serialization, except that only certain fields are
-traversed. We will see how to control which fields are detached in a later
-section.
-            </para>
-            <para>
-            <indexterm>
-                <primary>
-                    detachment
-                </primary>
-                <secondary>
-                    of dirty objects
-                </secondary>
-            </indexterm>
-When detaching an instance that has been modified in the current transaction
-(and thus made dirty), the current transaction is flushed. This means that when
-subsequently re-attaching the detached instances, OpenJPA assumes that the
-transaction from which they were originally detached was committed; if it has
-been rolled back, then the re-attachment process will throw an optimistic
-concurrency exception.
-            </para>
-            <para>
-You can stop OpenJPA from assuming the transaction will commit in the following
-ways :
-    <itemizedlist>
-        <listitem>
-            <para>
-                Invoke <methodname>EntityTransaction.setRollbackOnly
-                </methodname> prior to detaching your objects. Setting the 
-                <literal>RollbackOnly</literal> flag prevents OpenJPA from 
-                flushing when detaching dirty objects; instead OpenJPA just 
-                runs its pre-flush actions (see the 
-                <methodname>OpenJPAEntityManager.preFlush</methodname>
-<ulink url="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
-Javadoc</ulink> for details).
-            </para>
-            <para>
-This allows you to use the same instances in multiple
-attach/modify/detach/rollback cycles. 
-            </para>
-        </listitem>
-        <listitem>
-            <para>
-                Make your modifications outside of a transaction (with <literal>
-NontransactionalWrite</literal> enabled) before detaching.
-            </para>
-        </listitem>
-        <listitem>
-            <para>
-            Set <literal>flushBeforeDetach</literal> 
-            to false (see <methodname>Compatibility.setFlushBeforeDetach
-            </methodname>
-            <ulink url="../javadoc/org/apache/openjpa/conf/Compatibility.html">
-Javadoc</ulink> ). This option is similar to the first option, but does not
-            affect the current transaction.
-            </para>
-        </listitem>
-    </itemizedlist>
-    </para>
+<para>
+The behavior of the detach operation is as follows:
+<itemizedlist>
+	<listitem>
+		The detached objects are removed from the persistent context.
+	</listitem>
+	<listitem>
+		The objects are <emphasis>not</emphasis> flushed to the database.
+	</listitem>
+	<listitem>
+		If Cascade=detach is specified for a referenced entity, the detach
+		operation is cascaded. Otherwise, it is not.
+	</listitem>
+	<listitem>
+		For the detachCopy method only, the entity is copied for the return
+		value.
+	</listitem>
+</itemizedlist>
+</para>
         </section>
         <section id="ref_guide_attach_behavior">
             <title>