From f81908f3ac80c9c89c08c034e05eda20bb7f1b21 Mon Sep 17 00:00:00 2001
From: "Richard G. Curtis" <curtisr7@apache.org>
Date: Wed, 16 Nov 2011 17:30:19 +0000
Subject: [PATCH] OPENJPA-1986: Update migration consideration docs and
 Compatibility javadoc.

git-svn-id: https://svn.apache.org/repos/asf/openjpa/trunk@1202800 13f79535-47bb-0310-9956-ffa450edef68
---
 .../apache/openjpa/conf/Compatibility.java    |  4 ++--
 .../doc/manual/migration_considerations.xml   | 19 +++++++++++++++++++
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/openjpa-kernel/src/main/java/org/apache/openjpa/conf/Compatibility.java b/openjpa-kernel/src/main/java/org/apache/openjpa/conf/Compatibility.java
index 7fec3957f..495804cc3 100644
--- a/openjpa-kernel/src/main/java/org/apache/openjpa/conf/Compatibility.java
+++ b/openjpa-kernel/src/main/java/org/apache/openjpa/conf/Compatibility.java
@@ -558,7 +558,7 @@ public class Compatibility {
      * only applies for the case where we are trying to cascade a persist to an Entity which doesn't have a StateManager
      * and we can't determine if it is detached. 
      *   
-     * @since 2.1.x
+     * @since 2.1.1
      */
     public boolean getCheckDatabaseForCascadePersistToDetachedEntity(){
         return _checkDatabaseForCascadePersistToDetachedEntity;
@@ -569,7 +569,7 @@ public class Compatibility {
      * only applies for the case where we are trying to cascade a persist to an Entity which doesn't have a StateManager
      * and we can't determine if it is detached. 
      *   
-     * @since 2.1.x
+     * @since 2.1.1
      */
     public void setCheckDatabaseForCascadePersistToDetachedEntity(boolean b){
         _checkDatabaseForCascadePersistToDetachedEntity = b;
diff --git a/openjpa-project/src/doc/manual/migration_considerations.xml b/openjpa-project/src/doc/manual/migration_considerations.xml
index 1fc120827..a093772be 100644
--- a/openjpa-project/src/doc/manual/migration_considerations.xml
+++ b/openjpa-project/src/doc/manual/migration_considerations.xml
@@ -458,6 +458,25 @@
                     <xref linkend="jpa_2.2_allocationSize"/>.
                 </para>
             </section>            
+        	<section id="jpa_2.2_cascadePersist">
+                <title>
+                    Cascade persist behavior
+                </title>
+                <!-- See OPENJPA-1986 for details. -->
+				<para>
+					In previous releases, OpenJPA would check the database for the
+					existence of the related Entity before persisting the relationship to
+					that Entity. This resulted in an extra Select being sent to the
+					database. In 2.2.0, code was added so that when cascading a persist to
+					a related Entity without persistence state, the persist (insert) will
+					happen without first checking the database. This may result in an
+					EntityExistsException if the related Entity already exists in the
+					database. To revert this behavior to the previous release, set the
+					value of the <literal>openjpa.Compatibility</literal>
+					property <literal>CheckDatabaseForCascadePersistToDetachedEntity</literal>
+					to <literal>true</literal>.
+				</para>
+            </section>
         </section>
     </section>
 </appendix>