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

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

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

@@ -351,6 +351,26 @@ public class DBDictionary
     public String sequenceNameSQL = null;
     // most native sequences can be run inside the business transaction
     public int nativeSequenceType= Seq.TYPE_CONTIGUOUS;
+    
+    /**
+     * This variable was used in 2.1.x and prior releases to indicate that 
+     * OpenJPA should not use the CACHE clause when getting a native 
+     * sequence; instead the INCREMENT BY clause gets its value equal to the 
+     * allocationSize property.  Post 2.1.x, code was added to allow
+     * said functionality by default (see OPENJPA-1376).  For forward 
+     * compatibility, this variable should not be removed.
+     */
+    @Deprecated
+    public boolean useNativeSequenceCache = true;    
+    
+    /**
+     * If a user sets the previous variable (useNativeSequenceCache) to false, we should log a
+     * warning indicating that the variable no longer has an effect due to the code changes
+     * of OPENJPA-1376.  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 logNativeSequenceCacheWarning = true;    
 
     protected JDBCConfiguration conf = null;
     protected Log log = null;
@@ -3388,6 +3408,19 @@ public class DBDictionary
     public String[] getCreateSequenceSQL(Sequence seq) {
         if (nextSequenceQuery == null)
             return null;
+        
+    	//We need a place to detect if the user is setting the 'useNativeSequenceCache' property.
+    	//While in previous releases this property had meaning, it is no longer useful
+    	//given the code added via OPENJPA-1327.  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 useNativeSequenceCache 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 useNativeSequenceCache.
+    	if (!useNativeSequenceCache && logNativeSequenceCacheWarning){
+    		log.warn(_loc.get("sequence-cache-warning"));
+    		logNativeSequenceCacheWarning=false;
+    	}        
 
         StringBuilder buf = new StringBuilder();
         buf.append("CREATE SEQUENCE ");

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

@@ -224,3 +224,7 @@ 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.
+sequence-cache-warning: Setting the useNativeSequenceCache property on the DBDictionary no longer has an \
+    effect.  Code has been added to allow, by default, the functionality provided in previous releases \
+    via the useNativeSequenceCache property.
+    

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

@@ -444,6 +444,20 @@
                     has no effect in 2.1.x and later releases and any occurrence of it should be removed.
                 </para>
             </section>            
+            <section id="UseNativeSequenceCache">
+                <title>
+                    useNativeSequenceCache property.  
+                </title>
+                <!-- See OPENJPA-1376 for details. -->
+                <para>
+                    In the OpenJPA 2.2.x release, code was added which changed the way sequences were generated, please see 
+                    <xref linkend="jpa_2.2_allocationSize"/> for details.  This functionality was eventually back ported 
+                    to previous releases, and enabeld by the useNativeSequenceCache property on the DBDictionary.  Setting this property 
+                    has no effect in 2.2.x and later releases and any occurrence of it should be removed.  If previous behavior is
+                    desired (i.e. useNativeSequenceCache=true), please see the details described in section 
+                    <xref linkend="jpa_2.2_allocationSize"/>.
+                </para>
+            </section>            
         </section>
     </section>
 </appendix>

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

@@ -3419,6 +3419,27 @@ ResultSet.getString</methodname> will be used to obtain clob data rather than
                             UseSchemaName
                         </secondary>
                     </indexterm>
+<literal>UseNativeSequenceCache</literal>: This property was used in 
+2.1.x and prior releases to indicate (when set to false) that OpenJPA 
+should not use the CACHE clause when getting a native sequence; instead 
+the INCREMENT BY clause gets its value equal to the allocationSize 
+property.  Post 2.1.x, code was added to allow said functionality by 
+default (see OPENJPA-1376).  
+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="DBDictionary.UseNativeSequenceCache">
+                    <para>
+                    <indexterm>
+                        <primary>
+                            Sequence
+                        </primary>
+                        <secondary>
+                            UseNativeSequenceCache
+                        </secondary>
+                    </indexterm>
 <literal>UseSchemaName</literal>: If <literal>false</literal>, then avoid
 including the schema name in table name references. Defaults to <literal>true
 </literal>.