New or updated for this feature pack


Migration considerations when using JPA 2.0

Learn about the differences between Java Persistence API (JPA) 1.x and JPA 2.0 and how these changes affect the migration of your applications and runtime.

Consider the following changes or issues between JPA 1.x and JPA 2.0:

Areas of incompatibility

If you want to use applications that use a JPA 1.x release with applications that use JPA 2.0, your applications might not be compatible.

For example, if your application uses a Version 1.0 persistence.xml file, compatibility options are set appropriately to maintain backward compatibility. OpenJPA 2.0 applications that use a Version 2.0 persistence.xml file and require OpenJPA 1.x compatibility might need to configure the appropriate compatibility options to get the desired behavior.

The following are incompatible between Version 1.x and Version 2.0:
  • getProperties method

    The OpenJPAEntityManagerFactory interface getProperties method now returns a Map instead of a Properties object. This change was made in order to support the getProperties method that is defined in the JPA 2.0 specification.

  • Detach behavior

    In 1.x, OpenJPA had a detach() method on the OpenJPAEntityManager interface that returned an Entity. The JPA 2.0 specification introduced a detach() method on the EntityManager interface which has no return value and has different behavior than the 1.x method. This behavior change also applies to the other detach related methods on the OpenJPAEntityManager interface. The changes in behavior for all of these methods are as follows:

    • Applications that use a 1.0 persistence.xml file automatically maintain OpenJPA 1.0 behavior. It is possible for a version 2.0 application to revert back to the 1.x behavior for some of these items by setting the openjpa.Compatibility property as follows:
      Table 1. Settings
      openjpa.Compatibility property settings
      FlushBeforeDetach=true
      CopyOnDetach=true
      CascadeWithDetach=true
      A new method has also been provided on the OpenJPAEntityManager interface to return a copy of the entity:
      public <T> detachCopy(T pc): 
    • Since OpenJPAEntityManager is a subclass of of EntityManager, the detach() method was removed from the OpenJPAEntityManager. As a result, code that calls this method expecting a return value displays an error and needs to be re-written.
    • In the 1.x release, managed entities are flushed to the database as part of the detach operation. This is no longer done in 2.0.
    • In the 1.x release, entities are copied and returned. In 2.0, for those methods that have return values, the original entities are returned.
    • In the 1.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 or Cascade=all has been specified.
    • In the 1.x release, managed entities remain in the persistent context after one of the detach methods is executed. In 2.0, detached managed entities are removed from the persistent context as a result of the operation. If the CopyOnDetach Campatibility property is set to true, the managed entities are not removed.
  • Use of private persistent properties

    In 1.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 are not persistent by default.

    Applications that use a 1.0 persistence.xml file automatically maintain OpenJPA 1.x behavior. It is possible for a version 2.0 application to revert back to the 1.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.

  • Query.setParameters method

    As required by the JPA 2.0 Specification, the Query interface setParameters method behavior now displays an IllegalArgumentException if more parameter substitutions are supplied than defined in the createQuery or createNamedQuery method call. OpenJPA 1.2.x and prior versions silently ignore the supplied parameter substitutions and allow the Query to be processed.

  • Serialization of entities

    In 1.x.x releases of OpenJPA, when an entity was serialized after calling the methods, EntityManager.find(), detach() or detachAll(), all of the OpenJPA proxy wrapper classes were removed as expected. When the same entity instance was serialized after calling the method, 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 since the proxy classes use dynamically generated serialVersionUID values.

    This behavior has been modified with OpenJPA 2.0 so that when objects are serialized, the DetachedStateField is used to determine when build time proxies are removed. If proxies that are created at runtime are used (proxies not supplied by OpenJPA), or if an entity has already been detached, the found proxies are removed during serialization.
    • EntityManager.refresh

      As required by the JPA 1.0 and 2.0 Specification, the EntityManager refresh method throws an IllegalArgumentException if null is passed in. In prior releases OpenJPA incorrectly returned null.

    • transient

      Use a transient detached state field. This gives the benefits of a detached state field to local objects that are never serialized, but retains serialization compatibility for client tiers without access to the enhanced versions of your classes or the OpenJPA runtime. All proxies are removed during serialization. This is the default.

    • true

      Use a non-transient detached state field so that objects crossing serialization barriers can be attached efficiently. However, this requires that your client tier have the enhanced versions of your classes and the OpenJPA runtime. No OpenJPA provided proxies are removed during serialization.

    • false

      Do not use a detached state field. All proxies are removed during serialization. Applications that use a 1.0 persistence.xml automatically maintain the old behavior.

      It is possible for a version 2.0 application to revert back to the 1.x.x behavior by setting the following openjpa.Compatibility property as follows:
      IgnoreDetachedStateFieldForProxySerialization=true
      Include the following property in the persistence.xml:
      <property name="openjpa.Compatibility" value="IgnoreDetachedStateFieldForProxySerialization=true"/>

Default AutoOff collection tracking

The default behavior of tracking collections in OpenJPA is that if the number of modifications to the collection exceeds the current number of elements in collection, OpenJPA disables tracking the collections. JPA 2.0 adds a Compatibility property to disable turning off the collection tracking.

Automatically disabling 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 openjpa.Compatability property is set to false, the collection tracking is disabled automatically.

Internal behavior

The following sections indicate internal changes between OpenJPA 1.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.
  • FieldMapping.getStrategy method

    In OpenJPA 1.x, the FieldMapping.getStrategy method returned an instance of RelationFieldStrategy for embedded super classes. In JPA 2.0, this method returns an instance of EmbedFieldStrategy.

  • PreUpdate and PostUpdate life cycle callbacks

    If an entity was updated between the persist method and commit method operations in OpenJPA 1.x, the PreUpdate and PostUpdate life cycle callback methods are executed. Starting in OpenJPA 1.3 and 2.0, these callbacks are not executed.

    A note has been added to the JPA 2.0 section, "Semantics of the Life Cycle Callback Methods for Entities" that includes information about callback behavior.

  • createEntityManagerFactory exceptions

    The JPA 2.0 section, "Bootstrapping in Java Standard Edition Environments" states that persistence providers must return null if they are not a qualified provider for the given persistence unit. However, OpenJPA might throw a RuntimeException if an error occurs while trying to create a qualified persistence unit. for example, an error might occur for invalid openjpa.* specific configuration settings or for schema validation failures.

    If the Apache Geronimo JPA 2.0 Specification APIs are used, exceptions that are returned by a persistence provider are wrapped within a PersistenceException. When the JPA 2.0 API reference implementation is used, RuntimeExceptions are returned to the calling application are not wrapped. Other JPA 2.0 API and implementation providers or versions might behave differently.

  • openjpa.QueryCache default

    In previous releases, the default value for the openjpa.QueryCache property is true when the openjpa.DataCache is enabled. Depending on application characteristics, this default QueryCache enablement can reverse the performance gains that are achieved by using the DataCache. Therefore, the default value for the openjpa.QueryCache property has been changed to false.

    To re-enable the default QueryCache behavior, include the following property into your persistence.xml configuration:
    <property name="openjpa.QueryCache" value="true"/>
    If your configuration explicitly enabled the QueryCache and you relied on the prior release default, you might have to include the true value in the configuration. Otherwise, your current QueryCache enablement continues to work with JPA 2.0.



Related tasks
Task overview: Storing and retrieving persistent data with the JPA API
Related information
New or updated for this feature pack Apache OpenJPA User's Guide


Terms and conditions for information centers | Feedback

Last updatedLast updated: Jun 12, 2013 3:32:32 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=v700osgijpa&product=was-nd-mp&topic=rejb_jpa2mig
File name: rejb_jpa2mig.html