EclipseLink/Development/JPA

STATUS: PROPOSAL --Doug 13:23, 17 December 2007 (EST)

This page presents the PROPOSED strategy for implementing JPA 2.0 within EclipseLink.

Developing the functionality required for JPA 2.0 will involve careful planning in order to maintain compatibility with JPA 1.0 interfaces and annotations.

Requirements

1. Remain a compliant JPA 1.0 implementation during the development of 2.0 functionality. This is a major requirement since we are working towards a 1.0 release of EclipseLink which must be JPA 1.0 compliant.
   • This generally means that the JPA 1.0 persistence.jar could be on the classpath and the product should function as expected
2. Conform with the Eclipse IP process and rules. This means that the use of any updated persistence libraries and their source must come into the project through proper IP review procedures.
3. All new features involving changes to JPA's ORM-XML schema must be reflected in Eclipse-ORM.XML. This should be done in such a way that changes during the evolution of the specification are minimized.
4. Where possible any new features added for JPA 2.0 should also be available to users of the native EclipseLink ORM API and metadata. Accessibility through the native API can be limited to programmatic access and configuration.

Types of Changes

The JPA 2.0 expert group is attempting to evolve this new specification to remain backwards compatible with JPA 1.0. The scope of its work will involve changes of various types with different effects on EclipseLink.

1. Metadata Changes
   1. New Annotations
   2. New structures in the persistence.xml XSD
   3. New structures in the ORM.XML XSD
2. API Changes
   1. New interfaces
   2. New methods on existing interfaces

Development Approach

In order to support JPA 2.0 new capabilities will be added to EclipseLink's core object-relational foundation. These features will then be exposed through new JPA 2.0 metadata and corresponding processing. The goal is to first make these available and functional in the native API so that all object-relational consumers have access and to minimize JPA only capabilities. JPA is definitely the priority but by making the features available internally we can more easily proceed with development of JPA 2.0 related functionality without requiring a final specification definition of the metadata or having to deal with too much flux as the metadata approach evolves in the expert group.

Metadata Changes

New/Modified Annotations

Within JPA 2.0 there will be new annotations defined as well as modifications to existing annotations. In order to implement and test usage of these annotations within EclipseLink while still supporting JPA 1.0 custom annotations will be temporarily introduced.

--Mike 17:13, 20 December 2007 (EST)Creating code in a temporary package is not going to help us in the long run. We should create the new annotations in the proper package.

Temporary Annotations Package: org.eclipse.persistence.jpa

--Mike 17:13, 20 December 2007 (EST)If we *were* to create a temp package it should be one that will go away entirely, not one that already exists.

At the point in time where JPA 2.0 is approaching its final state and EclipseLink is going to switch from being a JPA 1.0 implementation to implementing the JPA 2.0 public API these custom annotations will be removed and the runtime will switch its dependencies to 2.0.

--Mike 17:13, 20 December 2007 (EST)And then what will happen? What happens to the requirement that EclipseLink work with a JPA 1.0 jar?

Potential Issues:

• Ensuring that the temporary annotation definitions implemented in EclipseLink under EPL do not violate Sun/JCP copyright or usage rules
• Ensuring that each of these temporary annotation definitions is clearly documented that it will be removed before final JPA 2.0 implementation is completed
• The implementation should strive to continue to function against JPA 1.0 if it were deployed in an EJB 3.0 container.

Replacing Existing EclipseLink Annotations

Q: Are there EclipseLink JPA extension annotations that exist today that will not be required in 2.0? What is the general strategy to handle these in EclipseLink 1.0?

API Changes

javax.persistence.EntityManager

Can we add API to org.eclipse.persistence.jpa.JpaEntityManager aligning with JPA 2.0 proposed API so that we can maintain support for JPA 1.0's EntityManager?

--Mike 17:13, 20 December 2007 (EST)Absolutely. Any additional methods will simply be seen as proprietary extensions when using the 1.0 API.

JPA 2.0 Features

The following are features known to be required for JPA 2.0

Note that plumbing for some of these features already does exist in EclipseLink while other parts are going to require feature additions.

Feature placeholders:

• embedded objects that can have relationships and other embedded objects nested within them

 • collections of embedded and basic objects

 • maps where keys and values can be any of basic, entity, or embedded (stored in a separate table, etc.)

 • ordered lists where the order is persisted on writes (order column)

 • Identifiers that contain relationships and are expressed in terms of the relationships (without an additional mapped FK property in the entity)

 • mixed attribute access types

 • orphan removal