Revision as of 10:59, 16 November 2007

Functional Specification: New XML metadata

Document History

Project overview

This project will expand our current JPA ORM implementation. Those features currently available from EclipseLink’s native XML file (deployment XML) and not available from JPA will be ported to a new EclipseLink ORM.xml schema.

Note this project will not address our OXM (JAXB, SDO) and EIS functionality. Those technologies will be addressed at a later time and should provide their own schema definitions etc. This project will concentrate solely on the ORM features available from EclipseLink.

Going forward, we would like to push our users towards our JPA implementation, eventually deprecating the old EclipseLink deployment XML.

Concepts

The following concepts are used in the document:

• Milestone – a 30 day development cycle
• Deployment XML – EclipseLink’s native metadata XML file used for project configuration.

Requirements

1. Design a runtime architecture that leverages our OXM for metadata loading in conjunction with annotations. This must handle JPA ORM.xml + annotations as well as our native XML and annotations.
2. Expand EclipseLink’s feature availability (beyond what is currently available) through the current JPA implementation
3. Support metadata loading schemes
   1. JPA only (annotations and XML)
   2. EclipseLink Native only (native annotations and XML)
   3. Oracle TopLink only
   4. JPA + EclipseLink Native
   5. JPA + Oracle TopLink – Not supported
4. Define a new XSD embracing minimal config, JPA ORM.xml alignment for overrides, and complete configuration without any JPA annotations or XML.
5. Ensure we can have a persistence unit defined with no entities. If a customer just wants to access the database using SQL or stored procedures they should be able to define a persistence unit with zero entities and just the named queries.
6. Be able to have named native SQL and stored procedure queries where the results can be shaped using any arbitrary entity or non-entity class. I think of this as constructor results for native queries.

Functionality

The new EclipseLink ORM.xml schema will be built from the existing JPA ORM.xml schema. That is, we will add new complex and simple elements to the schema.

The full functionality of EclipseLink and the existing native schema cannot be ported to the EclipseLink ORM.xml schema in one Milestone drop however. Will provide the new features throughout several Milestones. Milestone should include not only XML updates but also their annotation counterparts. Nothing should be added to the schema unless its internal processing is implemented, therefore, ensuring our users have a fully supported schema at the end of every Milestone.

The following Milestones serve as an example of our work going forth. Notice the Milestone content and ordering may be re-worked based on further discussions and priorities. Each Milestone will deliver a design, implementation and testing of the Milestone content.

JPA Configuration

Developers will be able to leverage this XML file for the purposes of JPA configuration. There are a number of ways this XML file can be used.

1. Usage of an EclipseLink ORM XML file anywhere (including default) a JPA ORM XML may exist. (Note: This may not be portable as other implementation may not be able to read them)

Default Location

As with JPA's default assumption that the existence of a META-INF/orm.xml indicates that it should be used for any persistence unit EclipseLink will have a default assumption that the existence of META-INF/eclipselink-orm.xml will be used. This file can exist in addition to JPA's META-INF/orm.xml as an override or in isolation.

The runtime will also support the default JPA META-INF/orm.xml being an EclipseLink ORM configuration file.

File Granularity

Developers will be able to use this native XML configuration file at the same granularity as a JPA ORM.XML. This means that within a persistence unit there can be zero or more files used

Note:

• At every Milestone, any remaining set of features not available through EclipseLink ORM.xml schema or annotations will remain available through the use of a session customizer.
• This document was created during Milestone 2

Milestone 3

• Convert the existing JPA XML metadata processing from SAX parsing to OX.

Milestone 4

• Design Spec
• This milestone will provide XML metadata support for existing native EclipseLink annotations.

Milestone 5

• Complex (PLSQL) type support for stored procedure parameters
• Sequencing on non-id attributes.
• attributes-complete - have a flag to indicate not to auto generate any unspecified attributes, this is important in XML when the class may continue to evolve.
• primary-key element to allow giving columns, (allow one-to-one pks, or including other fields such as the inheritance indicator, field from embeddable, etc.)
• allow target-join-column in a one-to-one (allows complex target foreign keys and one-to-one without mappedBy)

Milestone 6

• Transformation mappings
• Aggregate-collection mapping
• Variable 1-1 mapping
• Serialized Converter
• Class-instance converter

Milestone 7

• XML-type or data-type
• Query-keys
• Mapping custom-sql/calls
• Custom-sql/calls
• Mapping selection-criteria

Milestone 8

• Query sequence
• Unary-table sequence
• Copy-policy
• Instantiation-policy

Milestone 9

• Additional join
• Multiple table join
• Multiple table foreign-keys
• Inheritance-joins

Milestone 10

• Fetch groups
• Class extractor
• Additional events
• Does exist
• Default timeout
• Interfaces
• History

Milestone 11

•  ???

Milestone ???

• JPA 2.0 support

Also note that most metadata configurations from the JPA ORM.xml schema are optional. These optional components should continue within the EclipseLink ORM.xml schema wherever possible when adding new features. This will help maintain backwards compatibility and also avoid creating a new versioned schema for every new feature added and our users require little to hopefully no changes to their configurations.

Design Constraints

Expanding our feature set with the new ORM.xml schema will not proceed till our OX solution has been implemented. After that time, Milestones are free to be re-ordered or re-organized as necessary.

Maintainability

The maintainability of this project is greatly eased by updating our current JPA metadata processing to use our OX technology.

GUI

JPA comfigurations are supported through the Dali project. This project should be updated to support extended features made available from the new EclipseLink ORM.xml schema and annotations.

Config files

The Dali project should support writing out the EclipseLink ORM.xml file.