<?xml version="1.0" encoding="UTF-8"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
 http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->
<appendix id="migration_considerations" role="non-normative">
    <title>
        Migration Considerations
    </title>
    <section id="jpa_2.0">
        <title>
            OpenJPA 2.0.0
        </title>
        <section id="jpa_2.0_incompatibilities">
            <title>
                Incompatibilities
            </title>
            <!-- See OPENJPA-1208 for details. -->
            <para>
                The following sections indicate changes that are incompatible
                between OpenJPA 1.x.x releases and the 2.0 release. Some may
                require application changes. Others can be remedied through the
                use of compatibility options.  If your application uses a
                version 1.0 persistence.xml, compatibility options will be set
                appropriately to maintain backward compatibility.  OpenJPA 2.0
                applications using a version 2.0 persistence.xml and requiring
                OpenJPA 1.x.x compatibility may need to configure the
                appropriate compatibility options to get the desired behavior.
            </para>
            <section id="getProperties">
                <title>
                    getProperties()
                </title>
                <!-- See OPENJPA-849 for details. -->
                <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
                    JPA 2.0 specification.
                </para>
            </section>
            <section id="migration_detach_behavior">
                <title>
                    Detach Behavior
                </title>
                <!-- See OPENJPA-1215 for details. -->
                <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 cascaded to those entities for which
                                Cascade=detach has been specified.
                            </para>
                        </listitem>
                    </itemizedlist>
                </para>
                <para>
                    Applications that use a 1.0 persistence.xml will
                    automatically maintain OpenJPA 1.x.x behavior.  It is
                    possible for a version 2.0 application 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 id="private_persistent_properties">
                <title>
                    Use of private persistent properties
                </title>
                <!-- See OPENJPA-1176 for details. -->
                <para>
                    In 1.x.x releases of OpenJPA, if property access was used,
                    private properties were considered persistent. This is 
                    contrary to the JPA specification, which states that 
                    persistent properties must be public or protected.  In
                    OpenJPA 2.0 and later, private properties will not be 
                    persistent by default.
                </para>
                <para>
                    Applications that use a 1.0 persistence.xml will
                    automatically maintain OpenJPA 1.x.x behavior. It is
                    possible for a version 2.0 application to revert back to
                    the 1.x.x behavior by setting the value of the
                    <literal>openjpa.Compatibility</literal> 
                    property <literal>PrivatePersistentProperties</literal> to 
                    <literal>true</literal>.  If compile time enhancement is 
                    used, this property must be specified at the time of 
                    enhancement and at runtime.
                </para>
            </section>
            <section id="setParameter">
                <title>
                    Query.setParameter()
                </title>
                <!-- See OPENJPA-1213 for details. -->
                <para>
                    The Query interface setParameter() method behavior has
                    changed to throw an IllegalArgumentException (as required 
                    by the JPA specification) if more parameter substitutions 
                    are supplied than defined in the createQuery(), 
                    createNamedQuery(), or createNativeQuery() invocation.
                    OpenJPA 1.2.x and prior versions silently ignored these
                    extraneous parameter substitutions and allowed the Query
                    to be processed.
                </para>
            </section>
            <section id="serialization">
                <title>
                    Serialization of Entities
                </title>
                <!-- See OPENJPA-1097 and OPENJPA-1597 for details. -->
                <para>
                    In 1.x.x releases of OpenJPA, when an entity was serialized
                    after calling EntityManager.find(), detach() or detachAll()
                    then all <xref linkend="ref_guide_pc_scos_proxy"/>
                    references were removed as expected, but when the same
                    entity instance was serialized after calling
                    EntityManager.clear() the proxy classes were not removed.
                </para>
                <para>
                    This has two side-effects:
                    when entities are remoted across JVM boundaries (RPC)
                    or deserialized the OpenJPA runtime must be available
                    on the classpath (both client and server containers);
                    when entities are deserialized the OpenJPA runtime must
                    be the exact same revision as used to serialize the
                    entities due to the proxy classes using dynamically
                    generated serialVersionUID values.
                </para>
                <para>
                    Starting with OpenJPA 2.0, this behavior has been
                    modified, so that by default all proxies will be removed
                    during serialization.  See 
                    <xref linkend="ref_guide_pc_scos_proxy_serial"/> 
                    on how the behavior changes based on the 
                    <literal>DetachedStateField</literal> setting along with 
                    <xref linkend="ref_guide_detach_state"/> 
                    for more details on how to override the default
                    <literal>DetachedStateField</literal> setting.
                </para>
                <para>
                    Applications that use a 1.0 persistence.xml will
                    automatically maintain the old behavior.  It is
                    possible for a version 2.0 application to revert back to
                    the prior 1.x.x behavior by setting the following
                    openjpa.Compatibility property as follows:
                    <simplelist>
                        <member>IgnoreDetachedStateFieldForProxySerialization=true</member>
                    </simplelist>
                </para>
            </section>
            <section id="QuerySQLCache">
                <title>
                    openjpa.jdbc.QuerySQLCache
                </title>
                <!-- See OPENJPA-1179 for details. -->
                <para>
                    In prior 1.x.x releases, the openjpa.jdbc.QuerySQLCache
                    configuration property for Prepared SQL Cache accepted
                    value <literal>all</literal> to never drop items from the
                    cache, but this option is no longer supported and will cause
                    a PersistenceException with a root cause of a ParseException
                    to be thrown.  See 
                    <xref linkend="ref_guide_cache_querysql"/>
                    for details on the available configuration values.
                </para>
            </section>
        </section>
        <section id="Disabling AutoOff Collection Tracking">
            <title>
                Disabling AutoOff Collection Tracking
            </title>
            <!-- See OPENJPA-1223 and OPENJPA-1163 for details. -->
            <para>
                The default behavior of OpenJPA in tracking collections is that
                if the number of modifications to the collection exceeds the
                current number of elements in collection then OpenJPA will
                disable tracking the collections. OpenJPA 2.0 added a compatibility
                property to disable turning off the collection tracking.
            </para>
            <para>
                The behavior of Auto disabling of collection tracking can be
                avoided by setting the value of the
                <literal>openjpa.Compatibility</literal> property
                <literal>autoOff</literal> to  <literal>false</literal>.
                The default behavior of auto disabling the collection tracking
                is not changed. But when the above property is set then the
                collection tracking will not be disabled automatically.
            </para>
        </section>
        <section id="internal_differences">
            <title>
                Internal Behavioral Differences
            </title>
            <para>
                The following sections indicate internal changes between
                OpenJPA 1.x.x releases and the 2.0 release. As these are
                internal implementation specific behaviors not covered by
                the JPA specification, no changes should be required for
                applications that did not use or depend upon OpenJPA specific
                APIs or behavior.
            </para>
            
            <section id="prePostUpdate">
                <title>
                    PreUpdate/PostUpdate Life Cycle Callbacks
                </title>
                <!-- See OPENJPA-1182 for details. -->
                <para>
                    If an entity was updated between the persist()
                    and commit() operations in OpenJPA 1.x, then 
                    any PreUpdate and PostUpdate life cycle callback
                    methods would be executed.  Starting in OpenJPA
                    1.3 and 2.0, these callbacks will not get executed.
                </para>
                <para>
                    The JPA 2.0 specification section on "Semantics
                    of the Life Cycle Callback Methods for Entities"
                    has been updated to include a Note that the
                    callback behavior for updating an entity after
                    the persist operation is implementation specific
                    and should not be relied upon.
                </para>
            </section>
            <section id="createemf">
                <title>
                    createEntityManagerFactory Exceptions
                </title>
                <!-- See OPENJPA-1203 for details. -->
                <para>
                    The JPA 2.0 specification section on
                    "Bootstrapping in Java SE Environments" states
                    that persistence providers must return null
                    if they are not a qualified provider for the 
                    given persistence unit.
                </para>
                <para>
                    However, OpenJPA may throw a RuntimeException
                    if an error occurs while trying to create a
                    qualified persistence unit, like for invalid
                    openjpa.* specific configuration settings or
                    for schema validation failures.
                </para>
                <para>
                    If the Apache Geronimo JPA 2.0 Spec APIs are
                    used, then any exceptions returned by a
                    persistence provider will be wrapped within
                    a PersistenceException.  When the JPA 2.0 API
                    reference implementation is used, any
                    RuntimeExceptions will be returned to the
                    calling application without being wrapped.
                    Other JPA 2.0 API and implementation providers
                    or versions may behave differently.
                </para>
            </section>
            <section id="querycache">
                <title>
                    openjpa.QueryCache default
                </title>
                <!-- See OPENJPA-1469 and sub-tasks for details. -->
                <para>
                    In previous releases, the default value for the
                    openjpa.QueryCache property was <literal>true</literal>
                    when the openjpa.DataCache was enabled.  Depending on
                    application characteristics, this default QueryCache
                    enablement actually could negate much of the potential
                    gains achieved by using the DataCache.  Thus, the default
                    value for the openjpa.QueryCache property is now
                    <emphasis><literal>false</literal></emphasis>.
                </para>
                <para>
                    To re-enable the default QueryCache behavior, you need to
                    include the following property in your persistence.xml
                    configuration.
                    <programlisting>
    &lt;property name="openjpa.QueryCache" value="true"/&gt;
                    </programlisting>
                </para>
                <para>
                    If your configuration had previously enabled the QueryCache
                    explicitly, then you might have to include the
                    <literal>true</literal> value into your configuration
                    (if you relied on the previous default).  Otherwise, your
                    current QueryCache enablement will continue to work.
                    <programlisting>
    &lt;property name="openjpa.QueryCache" value="true(CacheSize=1000, SoftReferenceSize=100)"/&gt;
                    </programlisting>
                </para>
            </section>
        </section>
    </section>
    <section id="jpa_2.2">
        <title>
            OpenJPA 2.2.0
        </title>
        <section id="jpa_2.2_incompatibilities">
            <title>Incompatibilities</title>
       	    <para>
                The following sections indicate changes that are incompatible
                between OpenJPA 2.1.x releases and the 2.2.0 release.
            </para>
            <section id="jpa_2.2_allocationSize">
                <title>
                    allocationSize Property of Sequence Generator
                </title>
                <!-- See OPENJPA-1376 for details. -->
                <para>
                    In previous releases, specifying the <literal>allocationSize</literal> property of
                    <link linkend="jpa_overview_mapping_sequence_seqgen">sequence generator</link>
                    affected only sequence definition in the database. During
                    schema creation, the <literal>INCREMENT BY</literal> clause of
                    <literal>CREATE SEQUENCE</literal> statement always
                    had a value of 1 and on DB2, Oracle and PostgreSQL databases a <literal>CACHE</literal> clause
                    was added with the value of <literal>allocationSize</literal> property. Such a statement caused
                    sequence values being cached in the database. Starting with OpenJPA 2.2.0,
                    sequence values are cached in the jvm memory and the <literal>allocationSize</literal>
                    property determines size of that cache. The <literal>CACHE</literal> clause is no longer used,
                    instead the <literal>INCREMENT BY</literal> clause gets its value equal to the
                    <literal>allocationSize</literal> property. Such a strategy reduces the number of database roundtrips
                    required for retrieving sequence values considerably.
                </para>
                <para>
                    In order for the existing applications to work with OpenJPA
                    2.2.0, you have to manually recreate or redefine sequences, specifying
                    the correct <literal>INCREMENT BY</literal> value and, possibly, correct initial sequence value.
                    Note that the default value of the <literal>allocationSize</literal> property is 50 and that
                    value is used if the property is not specified.
                </para>
                <para>
                    The requirement for sequence modification applies to all databases that support sequences, regardless of
                    the <literal>CACHE</literal> clause being supported. The only exception is Firebird database -
                    since with this database the increment step is determined during sequence
                    value fetch, no migration activity is needed.
                </para>
                <para>
                    To maintain the old behavior of sequence generator in OpenJPA 2.2.0, you can:
                    <itemizedlist>
                        <listitem>
                            <para>
                                Set the <literal>allocationSize</literal> property value to 1.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                Additionally, if the <literal>CACHE</literal> clause has to be emitted in sequence definition,
                                this can be accomplished by overriding the
                                <ulink url="../javadoc/org/apache/openjpa/jdbc/sql/DBDictionary.html#getCreateSequenceSQL(org.apache.openjpa.jdbc.schema.Sequence)">
                                <methodname>DBDictionary.getCreateSequenceSQL</methodname></ulink> method.
                            </para>
                        </listitem>
                    </itemizedlist>
                </para>
            </section>
            <section id="jpa_2.2_metamodelArrays">
                <title>
                    MetaModel Attributes for Arrays  
                </title>
                <!-- See OPENJPA-2025 for details. -->
                <para>
                    In previous releases OpenJPA's MetaModel implementation generated a ListAttribute for every array. This behavior is correct if the array 
                    is annotated as a PersistentCollection, but not correct for un-annotated arrays (e.g. byte[], char[]). In OpenJPA 2.2.0 this behavior was corrected 
                    so that arrays which are not stored as PersistentCollections will use a SingularAttribute instead of a ListAttribute. 
                </para>
                <para>
                    If your application uses the MetaModel API and your entities contain arrays of any of the following types: byte[], Byte[], char[], Character[] and
                    do not use the @PersistentCollection annotation with those fields you will need to update your application to use OpenJPA 2.2.0.
                </para>
                <para> In order for the existing applications to work with OpenJPA you may: 
                    <itemizedlist>
                        <listitem>
                            <para> Regenerate the canonical metamodel classes</para>
                        </listitem>
                        <listitem>
                            <para> Set the Compatibility property <literal>UseListAttributeForArrays</literal> to <literal>true</literal> in persistence.xml 
                                <programlisting> &lt;property name="openjpa.Compatibility" value="UseListAttributeForArrays=true"/&gt;</programlisting>
                            </para>
                        </listitem>
                    </itemizedlist>    
                </para>
            </section>
            <section id="jpa_2.2_SupportsSetClob">
                <title>
                    supportsSetClob Property.  
                </title>
                <!-- See OPENJPA-1691 for details. -->
                <para>
                    In OpenJPA 2.2.0, code was added to allow the setting of CLOB or XML data larger than 4000 bytes.  This functionality
                    was eventually back ported to previous releases, and enabled by the <literal>supportsSetClob</literal> property on the OracleDictionary.  Setting this property 
                    has no effect in 2.2.0 and later releases and any occurrence of it should be removed.
                </para>
            </section>            
            <section id="jpa_2.2_UseNativeSequenceCache">
                <title>
                    useNativeSequenceCache Property.  
                </title>
                <!-- See OPENJPA-1376 for details. -->
                <para>
                    In OpenJPA 2.2.0, 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 enabled by the <literal>useNativeSequenceCache</literal> property on the DBDictionary.  Setting this property 
                    has no effect in 2.2.0 and later releases and any occurrence of it should be removed.  If previous behavior is
                    desired (i.e. <literal>useNativeSequenceCache=true</literal>), please see the details described in section 
                    <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 id="jpa_2.2_LifecycleEventManager">
                <title>
                    Life Cycle Event Manager Callback Behavior 
                </title>
                <!-- See OPENJPA-2163 for details. -->
                <para>
                    Life cycle event manager is used to manage entity's life cycle event callback.
                    In previous releases, Life cycle event manager is scoped to EntityManagerFactory.
                    This means listeners registered to an individual EntityManager may get life cycle
                    event callbacks for entity that it does not manage. 
                </para>
                <para>
                    From 2.2.1 release, the default callback behavior of the life cycle event manager
                    is changed to scope to each EntityManager.                     
                    To revert this behavior to the previous release, set the
                    value of the <literal>openjpa.Compatibility</literal>
                    property <literal>SingletonLifecycleEventManager</literal>
                    to <literal>true</literal>.
                </para>
            </section>
            <section id="jpa_2.2_sharedCacheMode">
                <title>
                    shared-cache-mode Property
                </title>
                <!-- See OPENJPA-1532 for details. -->
                <para>
                     In the previous release, when the shared-cache-mode is enabled and the DataCache property is not set 
                     or set to false, there will be no data caching.
                </para>
                <para>
                     From 2.2.2 release, the caching will be turned on if the shared-cache-mode is enabled. Please see the 
                     details described in section <xref linkend="ref_guide_shared_cache_mode_integration"/>.
                </para>
            </section>
        </section>
    </section>
    <section id="jpa_2.3">
        <title>
            OpenJPA 2.3.0
        </title>
        <section id="jpa_2.3_incompatibilities">
            <title>Incompatibilities</title>
       	    <para>
                The following sections indicate changes that are incompatible
                between OpenJPA 2.2.x releases and the 2.3.0 release.
            </para>    
            <section id="jpa_2.3_MappingTool">
                <title>
                    MappingTool Behavior for DB2 and Derby
                </title>
                <para>
                    In previous releases, the MappingTool mapped <literal>java.math.BigDecimal</literal> fields to the database type
                    DOUBLE, and as such, ignored <literal>column</literal> and <literal>precision</literal> values that might have been specified via the
                    <literal>javax.persistence.Column</literal> annotation.
                </para>
                <para>
                    From the 2.3.0 release, <literal>java.math.BigDecimal</literal> fields are now mapped to the database type DECIMAL
                    and it is very likely that you will need to specify <literal>column</literal> and <literal>precision</literal> via
                    the <literal>javax.persistence.Column</literal> annotation.
                </para>
            </section>
            <section id="jpa_2.3_RequiresSearchStringEscapeForLike">
                <title>
                    RequiresSearchStringEscapeForLike DBDictionary Property
                </title>
                <!-- See OPENJPA-2282 for details. -->
                <para>
                    In previous releases, the default value for the property RequiresSearchStringEscapeForLike is true and caused the 
                    unexpected escape clause appended to the SQL statement.
                    For example, user created a named query like this:
                    <programlisting> SELECT o.computerName FROM CompUser o WHERE o.name LIKE ?</programlisting>
                    At run time the following query is generated: 
                    <programlisting> SELECT t0.computerName FROM CompUser t0 WHERE (t0.name LIKE ? ESCAPE '\')</programlisting>                     
                    ESCAPE '\' shouldn't be appended to the query.
                </para>
                <para>
                    From the 2.3.0 release, RequiresSearchStringEscapeForLike property is set to false by default. You can configure 
                    RequiresSearchStringEscapeForLike property to be true if the old behavior is desired. 
                </para>
            </section>
            <section id="ReturnNullOnEmptyAggregateResult">
                <title>
                    Return value of aggregate functions in SELECT clause 
                </title>
                <!-- See OPENJPA-1794 for details. -->
                <para>
                    The JPA specification states "If SUM, AVG, MAX, or MIN is used, and there are no values to which the aggregate function can be
                    applied, the result of the aggregate function is NULL."  Prior to this update, OpenJPA incorrectly returned 0 for SUM, AVG, MIN, 
                    and MAX when a state field being aggregated is numeric.  This behavior affects both JPQL and Criteria queries.  With this update,
                    OpenJPA will return a null result value for these aggregate functions when a query returns no result.
                </para>
                <para>
                    To re-enable the prior behavior, you need to set the following persistence property in your persistence.xml or when
                    creating an EntityManagerFactory.
                    <programlisting>
    &lt;property name="openjpa.Compatibility" value="ReturnNullOnAggregateResult=false"/&gt;
                    </programlisting>
                </para>
            </section>
        </section>
    </section>
</appendix>
