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.
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 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.
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:
openjpa.Compatibility property settings |
---|
FlushBeforeDetach=true |
CopyOnDetach=true |
CascadeWithDetach=true |
public <T> detachCopy(T pc):
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.
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.
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.
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.
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.
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.
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.
IgnoreDetachedStateFieldForProxySerialization=trueInclude the following property in the persistence.xml:
<property name="openjpa.Compatibility" value="IgnoreDetachedStateFieldForProxySerialization=true"/>
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.
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.
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.
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.
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.
<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.