EclipseLink/Development/200040/FunctionalSpec

Functional Specification: New Native Object-Relational Mapping XML

ER 200040

Document History

Date	Author	Version Description & Notes
2007-11-15	Guy Pelletier	Initial Draft
2007-11-20	Doug Clarke	Flushing out requirements and functionality sections

Project overview

This project will introduce a new native XML configuration file that can be used to define the object-relational mapping metadata the EclipseLink runtime will use.

Goals:

• Improve the usability of the native ORM.XML file by making it more readable and less verbose (configuration by exception). Naming will align with JPA's ORM.XML to make usage of the native ORM.XML as intuitive as possible.
• Support various usage scenarios
  • As standalone mapping file(s) replacing the existing deployment project/map XML
  • As an override for JPA's ORM.XML enabled fine grain customization

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.

Concepts

The following concepts are used in the document:

• ORM.XML refers to the JPA specification defined XML configuration file which can be used within a persistence unit through reference in the persistence.xml or through default location (META-INF/orm.xml)
• EclipseLink-ORM.XML (EL-ORM.XML) – EclipseLink’s native metadata XML file which is being defined along with its usage within this project.

Requirements

The following sections will expand the goals of this project into more concrete requirements.

EclipseLink-ORM.XML XSD

A new XSD for defining EclipseLink's object-relational metadata will be defined:

1. Must support the complete functionality of the existing deployment project/map XML plus any additional features developed in parallel or selected for inclusion during the design process.
2. Must align with JPA's ORM.XML to make it both intuitive to use and also facilitate overriding. The new XSD will not import or reference JPA's ORM.XML but must instead align with it through common element and attribute naming.
3. Must embrace configuration by exception so only scope and non-default configurations need to be specified.

The XSD will be built from the existing JPA XSD. The new XSD will need to relax any requirements that are present in the JPA XSD. Currently no elements as a whole are required only certain attributes within specified elements are required in the JPA schema. Those elements and their requirements are as follows:

Element	Required attribute
<entity-mappings>	version
<entity>, <entity-listener>, <id-class>, <embeddable>, <mapped-superclass>	class
<pre-persist>, <post-persist>, <pre-remove>, <post-remove>, <pre-update>, <post-update>, <post-load>	method-name
<query-hint>	name, value
<named-query>, <named-native-query>, <sql-result-set-mapping>, <id>, <embedded-id>, <transient>, <version>, <column-result>, <secondary-table>, <attribute-override>, <association-override>, <basic>, <many-to-one>, <one-to-one>, <one-to-many>, <many-to-many>, <embedded>, <sequence-generator>, <table-generator>	name
<entity-result>	entity-class
<field-result>	name, column

Therefore, the current minimal configuration for a JPA orm.xml is:

<?xml version="1.0" encoding="UTF-8"?>
<entity-mappings version="1.0" 
   xmlns="http://java.sun.com/xml/ns/persistence/orm" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd">
</entity-mappings>

The new EclipseLink-ORM.xml file will need to ensure this minimal configuration remains in place meaning we can load both the JPA-ORM.xml and EclipseLink-ORM.xml against the same internal MOXy project.

EclipseLink-ORM.XML Processing

The usage of EclipseLink-ORM.XML file(s) will conform to the following processing rules:

1. Design a runtime architecture that leverages MOXy for metadata loading in conjunction with annotations. This must handle JPA (annotations + ORM.XML) as well as additional native EclipseLink options (annotations + EclipseLink-ORM.XML).
2. Expand EclipseLink’s feature availability within the EclipseLink-ORM.XML beyond what is currently available.
   • TO DO: Define candidate list of features that must be added during this process and file bugs for additional capabilities to be added later
3. Support multiple metadata loading schemes
   1. JPA only (annotations and XML)
   2. EclipseLink Native only (native annotations and XML)
   3. Oracle TopLink only: Support reading in and using Orcale TopLink's 11gR1 and 10.1.3 XML configuration files
   4. JPA + EclipseLink Native
   5. JPA + Oracle TopLink – Not supported. User's cannot load JPA with an Oracle TopLink project. They are mutually exclusive.
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.

EclipseLink-ORM.XML Locations

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.

Usage of the EclipseLink-ORM.XML file as an override for JPA annotations and/or ORM.XML. The files can be referenced for inclusion in a persistence unit's metadata definition through:

1. Default location
   1. META-INF/eclipselink-orm.xml
   2. META-INF/orm.xml (in place of JPA's ORM.XML. Note: This most certainly will not be portable)
   3. Referenced as persistence unit mapping file in persistence.xml
   4. Referenced through session configuration (sessions.xml)

Default Locations

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.

When both a META-INF/orm.xml and META-INF/eclipselink-orm.xml are specified, the contents of the META-INF/eclipselink-orm.xml will overlay the contents of the META-INF/orm.xml file. This solution works great in a one orm file approach, however, in a multi-file approach (that is using multiple persistence unit mapping files) this could pose some problems.

The current JPA implementation, assumes uniqueness between orm and mapping files. That is an entity is only ever defined once. The same entity defined twice within two seperate files will produce unexpected results since the last entity read will win. There is currently no guaranteed order of file processing.

Use case 1

META-INF/orm.xml - defines Entity A with the mappings b and c.

META-INF/eclipse-orm.xml - defines Entity A with the mappings for c and d.

Expected result - Entity A will contain the mapping b (from orm.xml), mapping c and d (from eclipse-orm.xml)

Use case 2

META-INF/orm.xml - defines Entity A with the mappings b and c.

META-INF/eclipse-orm.xml - defines Entity A with the mappings c and d.

META-INF/some-other-mapping-file.xml - defines Entity A with the mapping x.

Expected result - Entity A will contain the mapping b (from orm.xml), mapping c (from eclipse-orm.xml), mapping d (from eclipse-orm.xml) and mapping x (from some-other-mapping-file.xml)

Use case 3

META-INF/orm.xml - defines Entity A with the mappings b and c.

META-INF/extensions/eclipse-orm.xml (note: This file is then added through a <mapping-file> tag in the persistence.xml) - defines defines Entity A with the mappings c and d.

Expected result - Entity A will contain the mapping b (from orm.xml), mapping c and d (from eclipse-orm.xml)

Use case 4

META-INF/orm.xml - defines Entity A with the mappings b and c.

META-INF/jpa-mapping-file.xml - defines Entity A with the mappings a and d.

META-INF/extensions/eclipse-mapping-file.xml - defines defines Entity A with the mappings c and d.

Expected result - Entity A will contain the mapping a (from jpa-mapping-file.xml), mapping b (from orm.xml), mapping c and d (from eclipse-mapping-file.xml)

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.

Also, the EclipseLink-ORM.XML schema will relax the need to specify fully qualified classes. For those elements that require a class specification, the user may relax the qualifying of java lang classes (Byte, Double, Float, Integer, Long, Short, Boolean, Character, String etc ...)

EclipseLink-ORM.XML in place of JPA's ORM.XML

The EclipseLink runtime will support usage of EclipseLink-ORM.XML anywhere a JPA ORM.XML can be used. The runtime will automatically detect that the file is a native implementation and read and interpret its complete contents.

Note: It is important to document that this approach may introduce portability issues and that default EclipseLink naming or reference through a sessions configuration can also be used.

API access to EclipseLink-ORM.XML

The EclipseLink-ORM.XML file will be usable anywhere the previous deployment XML file can be used:

• Through an XMLProjectReader.
  • Loading multiple EclipseLink-ORM.XML files into a single project will require the use of a sessions.xml where the user may add additional projects.
  • Alternatively, the user may load multiple files individually and call:
    • primaryProject.addDescriptors(additionalProject)
    • primaryProject.addDescriptors(additionalProject, session) // where a session is available.
• Through SessionManager (XMLSessionConfigLoader) and SessionFactory

Backwards Compatibility

EclipseLink will support reading XML mapping files from Oracle TopLink 11 and 10.1.3. It will not be required to handle XML mapping files from early milestones of EclipseLink.

EclipseLink-ORM.XML Writing

The EclipseLink runtime currently supports writing out its native XML mapping file using MOXy. It is this support that the Workbench leverages to generate the deployment XML files. As part of this feature the writing of XML mapping files must be enhanced.

• When writing an EclipseLink project into XML the new EclipseLink-ORM.XML schema will be used for all object-relational projects.
  • Since the implementation of supporting the new EclipseLink-ORM.XML schema will be done across several Milestones, the write-out of the object-relational projects using the new EclipseLink-ORM.XML schema should be an option to the user. Forcing them to the EclipseLink-ORM.XML schema before it is fully defined and supported will cause users to 'lose' mapping information from their projects.
  • The Workbench will also need to populate a new configuration project model. It currently populates directly to an EclipseLink project.
• When writing an EclipseLink project into XML the current deploymentXML schema will be used for native MOXy and EIS projects

Writing Open Issues:

• Will the writing API be enhanced to support multiple file generation for custom granularity?
  • The user can then select which descriptors to write to which files.
• Will the writing API be enhanced to support writing out the common JPA ORM.XML content into standard ORM.XML file(s)?
  • The user will in-turn get two files (or more based on the point above). One conforming to JPA's ORM.XML schema and the second containing all the EclipseLink extensions into an EclipseLink-ORM.XML file.

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. NOTE: These Milestones will only include XML support. That is, annotation support along with XML override and merge capability will be provideded at a later date. 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.

This section discusses the implementation phases of this project.

• Milestone – a 30 day development cycle

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.
• NOTE: The Milestones below do not directly relate to an actual EclipseLink Milestone. Hence they will be labelled with a letter until such time that they are assigned to a specific Milestone.

Milestone a

• Convert the existing JPA XML metadata processing from SAX parsing to use MOXy. This is necessary to align all XML metadata reading into the same framework and thus enable a consistent implementation and support overriding.

Milestone b

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

Milestone c

• 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 d

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

Milestone e

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

Milestone f

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

Milestone g

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

Milestone h

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

Milestone i

•  ???

Milestone j

• 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.

Any file that is read in using the 11 or 10.1.3 format should be written out to the new EclipseLink-orm.file.

Documentation

Any documents that outline specific xml configurations should be listed here.

Open Issues

This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.

Issue #	Owner	Description / Notes
?	Owner	Description

Decisions

This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.

Issue #	Description / Notes	Decision
?	Description	Decision

Future Considerations

During the research for this project the following items were identified as out of scope but are captured here as potential future enhancements. If agreed upon during the review process these should be logged in the bug system.