OPENJPA-1691: Added property for forward compatibility, documented property and migration considerations.

git-svn-id: https://svn.apache.org/repos/asf/openjpa/trunk@1155056 13f79535-47bb-0310-9956-ffa450edef68

openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/sql/OracleDictionary.java

@@ -104,6 +104,25 @@ public class OracleDictionary
      * configure statements that it detects are operating on unicode fields.
      */
     public boolean useSetFormOfUseForUnicode = true;
+    
+    /**
+     * This variable was used prior to 2.1.x to indicate that OpenJPA should attempt to use
+     * a Reader-based JDBC 4.0 method to set Clob or XML data.  It allowed XMLType and 
+     * Clob values larger than 4000 bytes to be used.  For 2.1.x+, code was added to allow
+     * said functionality by default (see OPENJPA-1691).  For forward compatibility, this 
+     * variable should not be removed.
+     */
+    @Deprecated
+    public boolean supportsSetClob = false;  
+    
+    /**
+     * If a user sets the previous variable (supportsSetClob) to true, we should log a
+     * warning indicating that the variable no longer has an effect due to the code changes
+     * of OPENJPA-1691.  We only want to log the warning once per instance, thus this
+     * variable will be used to indicate if the warning should be printed or not.  
+     */
+    @Deprecated
+    private boolean logSupportsSetClobWarning = true;
 
     /**
      * Type constructor for XML column, used in INSERT and UPDATE statements.
@@ -572,6 +591,20 @@ public class OracleDictionary
     public void setClobString(PreparedStatement stmnt, int idx, String val,
         Column col)
         throws SQLException {
+    	
+    	//We need a place to detect if the user is setting the 'supportsSetClob' property.
+    	//While in previous releases this property had meaning, it is no longer useful
+    	//given the code added via OPENJPA-1691.  As such, we need to warn user's the
+    	//property no longer has meaning.  While it would be nice to have a better way
+    	//to detect if the supportsSetClob property has been set, the best we can do
+    	//is detect the variable in this code path as this is the path a user's code
+    	//would go down if they are still executing code which actually made use of
+    	//the support provided via setting supportsSetClob.
+    	if (supportsSetClob && logSupportsSetClobWarning){
+    		log.warn(_loc.get("oracle-set-clob-warning"));
+    		logSupportsSetClobWarning=false;
+    	}
+
         if (col.isXML()) {
             if (isJDBC4) {
                 // This JDBC 4 method handles values longer than 4000 bytes.

openjpa-jdbc/src/main/resources/org/apache/openjpa/jdbc/sql/localizer.properties

@@ -221,3 +221,6 @@ sequencesql-override: Going to override the DB2 specific default for the \
     string and the string set in the property and will further allow openJPA to use the \
     string defined by the property rather than the default string for DB2.
 invalid-locking-mode: Invalid locking mode for SolidDB: "{0}"
+oracle-set-clob-warning: Setting the supportsSetClob property on the OracleDictionary no longer has an \
+    effect.  Code has been added to allow, by default, the functionality provided in previous releases \
+    via the supportsSetClob property.

openjpa-project/src/doc/manual/migration_considerations.xml

@@ -433,6 +433,17 @@
                     </itemizedlist>    
                 </para>
             </section>
+            <section id="SupportsSetClob">
+                <title>
+                    supportsSetClob property.  
+                </title>
+                <!-- See OPENJPA-1691 for details. -->
+                <para>
+                    In the OpenJPA 2.1.x release, code was added to OpenJPA to allow the setting of Clob or XML data larger than 4000 bytes.  This functionality
+                    was eventually back ported to previous releases, and enabeld by the supportsSetClob property on the OracleDictionary.  Setting this property 
+                    has no effect in 2.1.x and later releases and any occurrence of it should be removed.
+                </para>
+            </section>            
         </section>
     </section>
 </appendix>

openjpa-project/src/doc/manual/ref_guide_dbsetup.xml

@@ -3865,6 +3865,18 @@ on database configuration, e.g. encoding. This property defines the maximum size
 CLOB to persist with the embedded method. Defaults to 4000 characters.
                     </para>
                 </listitem>
+                <listitem id="OracleDictionary.SupportsSetClob">
+                    <para>
+<literal>SupportsSetClob</literal>: This property was used in previous releases 
+to indicate that OpenJPA should attempt to use a Reader-based JDBC 4.0 method to 
+set Clob or XML data.  It allowed XMLType and Clob values larger than 4000 bytes 
+to be used.  For this release, and newer, code was added to allow said 
+functionality by default (see OPENJPA-1691).  For forward compatibility, this 
+property still remains, however it has been deprecated and will eventually be
+removed.  Setting this property has no effect and any occurrence of it should
+be removed.
+                    </para>
+                </listitem>                
                 <listitem id="OracleDictionary.UseSetFormOfUseForUnicode">
                     <para>
 <literal>UseSetFormOfUseForUnicode</literal>: Prior to Oracle 10i, statements