![[8.5.5.6 or later]](../ng_v8556.gif)
Java Persistence API 2.1 behavior changes
If you already use the jpa-2.0 feature for your applications, you are encouraged to continue using the jpa-2.0 feature for your existing applications to avoid any migration issues. For new applications, you are encouraged to use the jpa-2.1 feature, which enables you to take advantage of the new features 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
There are a few major differences between the jpa-2.0and jpa-2.1 features that you need to be aware of:
- PersistenceProvider class name
- 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
-
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. See the documentation on the enhancement of JPA entities for more information.
-
jpa-2.1: EclipseLink works with unenhanced entities. WebSphere Application Server supports static enhancement.
Some features might be unavailable, such as lazy loading and some performance gains.
- If entities classes are statically enhanced for use with thejpa-2.0 (OpenJPA) provider, the classes must be recompiled before you use the jpa-2.1 provider.
- 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 reading 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 new 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
-
This feature enables you to 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
-
This feature enables you to 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
This feature enables you to invoke procedures 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
-
This feature enables you to 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