Java Persistence API 2.1 behavior changes

If you already use the jpa-2.0 feature for your applications, continue using the jpa-2.0 feature for your existing applications to avoid any migration issues. For new applications, it is best to use the jpa-2.1 feature, which enables you to take advantage of the new features that are available in the JPA 2.1 specification. If you want to change your existing applications to use the jpa-2.1 feature instead of the jpa-2.0 feature, you might need to adjust your application in the migration process.

Differences between jpa-2.0 and jpa-2.1

Be aware of a few major differences between the jpa-2.0 and jpa-2.1 features. See the following:

PersistenceProvider class name differences
jpa-2.0
  • IBM® provider:com.ibm.websphere.persistence.PersistenceProviderImpl
  • OpenJPA provider: org.apache.openjpa.persistence.PersistenceProviderImpl
jpa-2.1
  • org.eclipse.persistence.jpa.PersistenceProvider
Caching behavior differences

jpa-2.0: Caching is disabled by default. If your application needs to take advantage of a L2 cache, you must explicitly enable it.

jpa-2.1: By default, the EclipseLink provider has the L2 cache and QueryCache enabled. You must ensure that this setting is the best option for your applications. If you are running in a distributed environment, like a cluster, you need to disable the cache, or understand that different nodes can have different data.

Enhancement / weaving differences

jpa-2.0: OpenJPA requires entities to be enhanced. For more information, see Enhancement of JPA entities for JPA 2.0 in the product documentation.

jpa-2.1: EclipseLink works with unenhanced entities. WebSphere Application Server supports static enhancement.

Some features might not be available, such as lazy loading and some performance gains.

  • If entity classes are statically enhanced for use with the jpa-2.0 (OpenJPA) provider, the classes must be recompiled before you use the jpa-2.1 provider.
  • If Liberty is configured to use the jpa-2.1 feature and the entities are enhanced by using OpenJPA enhancement, the following error is thrown:
    java.lang.NoClassDefFoundError: 
org.apache.openjpa.enhance.PersistenceCapable.
  • The NoClassDefFoundError occurs because OpenJPA classes are not available to the server at run time when the Liberty server is configured to use jpa-2.1.
    • To resolve this issue, recompile the application and ensure that the entities are not enhanced with the OpenJPA enhancer. Either do not enhance the entities at all, or enhance the entities by using EclipseLink enhancement instead of OpenJPA enhancement.
    • Alternatively, leave the entities in their enhanced state and reconfigure Liberty to use the jpa-2.0 feature. The result is some loss of functionality from JPA 2.1.
Data source usage differences

The jpa-2.0 feature sparingly uses the non-jta-datasource, so few non-jta-datasource connections are required when you are tuning an application.

The jpa-2.1 uses a non-jta-datasource connection when it reads data and a transaction is not active. This means that non-jta-datasource connection pools need to be larger when you use this feature.

See the OpenJPA -> EclipseLink migration guide page for more differences between the two JPA providers.

JPA 2.1 features available in OpenJPA

OpenJPA, the JPA 2.0 provider, has features that function similarly to the new JPA 2.1 features. This means that if you have an existing application that uses the jpa-2.0 feature and want to use some of the JPA 2.1 features, you do not have to switch to the jpa-2.1 feature. Instead, you can use the equivalent of the new feature that is provided by OpenJPA. Some of the key JPA 2.1 features that are available in OpenJPA are:

Schema Generation

With this feature, you can generate DDL or interact directly with the database to define table schemas based on JPA entity definition. For more information, refer to section 9.4 of the JPA 2.1 Specification.

OpenJPA equivalent feature: Schema Mapper

Entity Graphs

With this feature, you can specify fetching or processing of a graph of entity objects. For more information, refer to section 3.7 of the JPA 2.1 Specification.

OpenJPA equivalent feature: FetchPlan and FetchGroup

Stored Procedure Queries

With this feature, you can invoke procedures that are stored in databases. For more information, refer to section 3.10.17 of the JPA 2.1 Specification.

OpenJPA equivalent feature: Query invocation

Basic Attribute Type conversion

With this feature, you can convert between an attribute entity representation and database representation for basic type attributes. For more information, refer to section 3.8 of the JPA 2.1 Specification.

OpenJPA equivalent feature: Externalizer feature

@Index and @ForeignKey annotations

Refer to sections 11.1.19 and 11.1.23 of the JPA 2.1 Specification.

OpenJPA equivalent feature: OpenJPA's @Index and @ForeignKey.

Unwrap utility methods for EntityManager, Cache

Refer to sections 3.1.1 and 7.10 of the JPA 2.1 Specification.

OpenJPA equivalent features: EntityManagerImpl.unwrap() and OpenJPAPersistence.cast().

Object construction when mapping results from native SQL

Refer to Section 3.10.16.2.2 of the JPA 2.1 Specification.

OpenJPA equivalent feature: ResultShape object.