Table of Contents
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 require OpenJPA 1.x.x compatibility may need to configure the appropriate compatibility options to get the desired behavior.
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.
The detach behavior has changed in several ways:
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.
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.
In the 1.x.x release, managed entities still exist in the persistent context. In 2.0, they are removed.
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.
Applications that use a 1.0 persistence.xml will automatically maintain OpenJPA 1.0 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:
| CopyOnDetach=true | 
| FlushBeforeDetach=true | 
| CascadeWithDetach=true | 
                    In addition, a new method has been provided on the
                    
                    OpenJPAEntityManager
                    interface to return a copy of the entity:
                    
    public <T> T detachCopy(T pc):
                    
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.
                    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
                    openjpa.Compatibility 
                    property PrivatePersistentProperties to 
                    true.  If compile time enhancement is 
                    used, this property must be specified at the time of 
                    enhancement and at runtime.
                
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.
In 1.x.x releases of OpenJPA, when an entity was serialized after calling EntityManager.find(), detach() or detachAll() then all Section 6.4, “ Proxies ” references were removed as expected, but when the same entity instance was serialized after calling EntityManager.clear() the proxy classes were not removed.
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.
                    Starting with OpenJPA 2.0, this behavior has been
                    modified, so that by default all proxies will be removed
                    during serialization.  See 
                    Section 6.4.4, “
                    Serialization
                ” 
                    on how the behavior changes based on the 
                    DetachedStateField setting along with 
                    Section 1.3.1, “
                    Detached State
                ” 
                    for more details on how to override the default
                    DetachedStateField setting.
                
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:
| IgnoreDetachedStateFieldForProxySerialization=true | 
                    In prior 1.x.x releases, the openjpa.jdbc.QuerySQLCache
                    configuration property for Prepared SQL Cache accepted
                    value all 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 
                    Section 3, “Prepared SQL Cache”
                    for details on the available configuration values.
                
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. Added a Compatibility property to disable turning off the collection tracking.
                The behavior of Auto disabling of collection tracking can be
                avoided by setting the value of the
                openjpa.Compatibility property
                autoOff to  false.
                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.
            
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.
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.
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.
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.
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.
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.
                    In previous releases, the default value for the
                    openjpa.QueryCache property was true
                    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 will now by
                    false.
                
To re-enable the default QueryCache behavior, you need to include the following property in your persistence.xml configuration.
    <property name="openjpa.QueryCache" value="true"/>
                    
                    If your configuration had previously enabled the QueryCache
                    explicitly, then you might have to include the
                    true value into your configuration
                    (if you relied on the previous default).  Otherwise, your
                    current QueryCache enablement will continue to work.
                    
    <property name="openjpa.QueryCache" value="true(CacheSize=1000, SoftReferenceSize=100)"/>