1.1.
Incompatibilities

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.

1.1.1.
getProperties()

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.

1.1.2.
Detach Behavior

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):

1.1.3.
Use of private persistent properties

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.

1.1.4.
Query.setParameter()

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.

1.1.5.
Serialization of Entities

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

1.1.6.
openjpa.jdbc.QuerySQLCache

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.

1.2.
Disabling AutoOff Collection Tracking

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.

1.3.
Internal Behavioral Differences

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.

1.3.1.
PreUpdate/PostUpdate Life Cycle Callbacks

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.

1.3.2.
createEntityManagerFactory Exceptions

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.

1.3.3.
openjpa.QueryCache default

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.