Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

EclipseLink/Development/200040/FunctionalSpec

Functional Specification: EclipseLink ORM 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
2007-11-29 Guy Pelletier Further flushing out requirements and functionality sections
2007-12-05 Guy Pelletier Flushing out overriding and merging 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 (it should grab JPA's namespace where available).
  3. Must embrace configuration by exception so only scope and non-default configurations need to be specified.
  4. Must embrace minimal config, 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.

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

Element Required attribute(s) 
<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 an ORM.XML file 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 EclipseLink-ORM.XML schema will need to ensure this minimal configuration remains in place meaning we can load both the 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.
    • See Functionality section below
  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

Note: JPA + Oracle TopLink loading is currently not supported and will not be added at this time.

EclipseLink-ORM.XML Locations

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

Usage of the EclipseLink-ORM.XML file as an override for JPA and EclipseLink 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 or any other JPA mapping file that is specified in the persistence unit.

Override and Merging Rules

The EclipseLink-ORM.XML override will only occur when the user defines the following file:

  • META-INF/eclipselink-orm.xml

Any other mapping file, regardless if it conforms to the EclipseLink-ORM.XML schema will be treated no differently than any other JPA ORM.XML file. If there are overlapping specifications in multiple orm files, the last file read will win and there is no guarantee in which order the mapping files will be processed. NOTE: The order the files are listed in the persistence.xml file does not not guarantee that they will be processed in that order.

The overall overriding rule will be at the 'mapping' level. However, the following sections below outline those elements already defined in the ORM.XML (hence can be specified in the EclipseLink-ORM.XML file) and their specific overriding in greater detail.

Also note that even though this file may provide extensions to entities in other mapping files it may also at the same time provide complete specifications of other entities and classes. Therefore, after any extensions/overlays have been applied, this field will still be processed like any other mapping file.

Persistence Unit Metadata

Currently a persistence-unit-metadata specification is to be defined in one and only one mapping file and it is an error to do otherwise (unless the specifications are identical). In the EclipseLink-ORM.XML case, a persistence-unit-metadata specification will merge and/or override the values of existing persistence-unit-metadata specification.

entity-mappings/persistence-unit-metadata Rule Comments
xml-mapping-metadata-complete Full override An xml-mapping-unit-metadata setting will override an existing setting (non-set that is) and set one. And the functionality remains as defined in the JPA spec. If specified then the complete set of mapping metadata for the persistence unit is contained in the XML mapping files for the persistence unit.
persistence-unit-defaults/schema Full override A schema setting will override an existing setting or set one
persistence-unit-defaults/catalog Full override A catalog setting will override an existing setting or set one
persistence-unit-defaults/access Full override An access setting will override an existing setting or set one
entity-mappings/persistence-unit-metadata/persistence-unit-defaults/cascade-persist Full override A cascade-persist setting will override an existing setting or set one
entity-mappings/persistence-unit-metadata/persistence-unit-defaults/entity-listeners Full override Any listeners defined here will override existing listeners and add new ones

Entity Mappings

Entities, embeddables and mapped superclasses are defined within entity-mappings but are discussed in later sections. New entities, embeddables and mapped superclasses (that is solely defined in the EclipseLink-ORM.XML file) will be added to the persistence unit whereas otherwise will be merged and overridden as specified in their related sections below. The top level elements of the entity-mappings sections will be discussed here.

entity-mappings/ Rule Comments
package None The package element specifies the package of the classes listed within the subelements and attributes of the same mapping file only. That is, will only apply to those entities that are fully defined within the EclipseLink-ORM.XML file, othwerwise its usage remains local and the same as described in the JPA spec.
catalog None The catalog element applies only to the subelements and attributes listed within the EclipseLink-ORM.XML file that are NOT an extension to another mapping file. Otherwise, the use of the catalog element within the EclipseLink-ORM.XML file remains local and the same as described in the JPA spec.
schema None The schema element applies only to the subelements and attributes listed within the EclipseLink-ORM.XML file that are NOT an extension to another mapping file. Otherwise, the use of the schema element within the EclipseLink-ORM.XML file remains local and the same as described in the JPA spec.
access None The access element applies only to the subelements and attributes listed within the EclipseLink-ORM.XML file that are NOT an extension to another mapping file. Otherwise, the use of the access element within the EclipseLink-ORM.XML file remains local and the same as described in the JPA spec.
sequence-generator Full override A sequence-generator is unique by name. A sequence-generator with the same named defined in another mapping file will be completely overridden by this sequence-generator. Two sequence-generator's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
table-generator Full override A table-generator is unique by name. A table-generator with the same named defined in another mapping file will be completely overridden by this table-generator. Two table-generator's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
named-query Full override A named-query is unique by name. A named-query with the same named defined in another mapping file will be completely overridden by this named-query. Two named-query's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
named-native-query Full override A named-native-query is unique by name. A named-native-query with the same named defined in another mapping file will be completely overridden by this named-native-query. Two named-native-query's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
sql-result-set-mapping Full override A sql-result-set-mapping is unique by name. A sql-result-set-mapping with the same named defined in another mapping file will be completely overridden by this sql-result-set-mapping. Two sql-result-set-mapping's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.

Mapped Superclass

A mapped-superclass can be defined wholely or may be defined so as to provide extensions to a mapped-superclass from another mapping file. Therefore, we will allow the merging of that classes metadata. The individual override rules for that metadata is tabled below.

entity-mappings/mapped-superclass Rule Comments
id-class Full override An id-class setting will override an existing setting or set one.
exclude-default-listeners Full override An exclude-default-listeners setting will override an existing setting or set one.
exclude-superclass-listeners Full override An exclude-superclass-listeners setting will override an existing setting or set one.
entity-listeners Full override Any listeners defined here will override existing listeners and add new ones. The class name of the listener will be the key to identify the override. All the lifecycle methods of that listener will be overridden.
pre-persist Full override A pre-persist setting will override an existing setting or set one.
post-persist Full override A post-persist setting will override an existing setting or set one.
pre-remove Full override A pre-remove setting will override an existing setting or set one.
post-remove Full override A post-remove setting will override an existing setting or set one.
pre-update Full override A pre-update setting will override an existing setting or set one.
post-update Full override A post-update setting will override an existing setting or set one.
post-load Full override A post-load setting will override an existing setting or set one.
attributes Merge and mapping level override All attributes will be overriden at the mapping level (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) and new attributes will be added.
class None
access Full override An access setting will override an existing setting or set one. It will override the default class setting.
metadata-complete Full override A metadata-complete setting will override an existing setting or set one.

entity override and merging rules

An entity can be defined wholely or may be defined so as to provide extensions to an entity from another mapping file. Therefore, we will allow the merging of that classes metadata. The individual override rules for that metadata is tabled below.

entity-mappings/entity Rule Comments
table Full override A table definition will override any other table setting (with the same name) for this entity. There will be no merging of individual table values.
secondary-table Full override A secondary-table definition will override another seconday-table setting (with the same name) for this entity. There will be no merging of individual secondary-table(s) values. New secondary-table's will be added.
primary-key-join-column Full override A primary-key-join-column(s) definition will override any other primary-key-join-column(s) setting for this entity. There will be no merging of the primary-key-join-column(s). That is, the specification is assumed to be complete and these primary-key-join-columns are the source of truth.
id-class Full override An id-class setting will override an existing setting or set one.
inheritance Full override An inheritance setting will override an existing setting or set one.
discriminator-value Full override A discriminator-value setting will override an existing setting or set one.
discriminator-column Full override A discriminator-column setting will override an existing setting or set one.
sequence-generator Full override A sequence-generator is unique by name. A sequence-generator with the same named defined in another mapping file will be completely overridden by this sequence-generator. Two sequence-generator's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
table-generator Full override A table-generator is unique by name. A table-generator with the same named defined in another mapping file will be completely overridden by this table-generator. Two table-generator's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
named-query Full override A named-query is unique by name. A named-query with the same named defined in another mapping file will be completely overridden by this named-query. Two named-query's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
named-native-query Full override A named-native-query is unique by name. A named-native-query with the same named defined in another mapping file will be completely overridden by this named-native-query. Two named-native-query's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
sql-result-set-mapping Full override A sql-result-set-mapping is unique by name. A sql-result-set-mapping with the same named defined in another mapping file will be completely overridden by this sql-result-set-mapping. Two sql-result-set-mapping's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
exclude-default-listeners Full override An exclude-default-listeners setting will override an existing setting or set one.
exclude-superclass-listeners Full override An exclude-superclass-listeners setting will override an existing setting or set one.
entity-listeners Full override Any listeners defined here will override existing listeners and add new ones. The class name of the listener will be the key to identify the override. All the lifecycle methods of that listener will be overridden.
pre-persist Full override A pre-persist setting will override an existing setting or set one.
post-persist Full override A post-persist setting will override an existing setting or set one.
pre-remove Full override A pre-remove setting will override an existing setting or set one.
post-remove Full override A post-remove setting will override an existing setting or set one.
pre-update Full override A pre-update setting will override an existing setting or set one.
post-update Full override A post-update setting will override an existing setting or set one.
post-load Full override A post-load setting will override an existing setting or set one.
attributes Merge and mapping level override All attributes will be overriden at the mapping level (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) and new attributes will be added.
association-override Merge and full override Any association-overide defined here will override an existing association-override and add new ones.
name Full override An name setting will override an existing setting or set one.
class None
access Full override An access setting will override an existing setting or set one. It will override the default class setting.
metadata-complete Full override A metadata-complete setting will override an existing setting or set one.

Embeddable

An embeddable can be defined wholely or may be defined so as to provide extensions to an embeddeable from another mapping file. Therefore, we will allow the merging of that classes metadata. The individual override rules for that metadata is tabled below.

entity-mappings/embeddable Rule Comments
attributes Override and merge At the mapping level (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient)
class None
access Full override An access setting will override an existing setting or set one. It will override the default class setting.
metadata-complete Full override A metadata-complete setting will override an existing setting or set one.

Use cases

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.
  • 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/some-other-mapping-file.xml - defines Entity B with the mappings a and b
  • META-INF/eclipse-orm.xml - defines Entity A with the mappings for c and d and Entity B with the mapping b and c
  • Result
    • Entity A will contain the mapping b (from orm.xml), mapping c and d (from eclipse-orm.xml)
    • Entity B will contain the mapping a (from some-other-mapping-file), mappings b and c (from eclipse-orm.xml)
Use case 3
  • 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.
  • Result - Ambiguous. User will either get 1 of the following results.
    • Entity A will contain the mapping b (from orm.xml) and mapping c and d (from eclipse-orm.xml), or
    • Entity A will contain the mappings c and d (from eclipse-orm.xml) and mapping x (from some-other-mapping-file)
Use case 4
  • 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.
  • Result - Ambiguous. Entity A will defined from orm.xml or /extensions/eclipse-orm.xml based on which files was read last.
Use case 5
  • 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.
  • Result - Ambiguous. Entity A will defined from orm.xml or jpa-mapping-file.xml or /extensions/eclipse-mapping-file.xml based on which files was read last.

File Granularity

Developers will be able to use the EclipseLink-ORM.XML 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

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

Note: When a EclipseLink-ORM.XML file is loaded (as a deployment XML file), any annotations defined on those classes from that XML file will be processed as well.

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 deployment XML mapping file using MOXy. It is this support that the Workbench leverages to generate these 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.
    • Default values should not be written.
  • When writing an EclipseLink project into XML the current deploymentXML schema will be used for native MOXy and EIS projects

The writing will maintain its current functionality of writing to a single file only.

Functionality

The full functionality of EclipseLink and the existing native schema cannot be ported to the EclipseLink-ORM.XML schema in one Milestone drop. The full list of features will be provided across several Milestones. Each feature currently not supported by the EclipseLink-ORM.XML schema is (and should continue to be) entered as a bug. The bugs will then be addressed in later Milestones.

NOTE: Each bug (feature request) includes not only the XML support but the annotation support with the associated XML override and merging capabilities.

Nothing should be ever 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. At every Milestone, any remaining set of features not available through the EclipseLink-ORM.XML schema or annotations will remain available through the use of a session customizer.

The following bugs have been entered against the EclipseLink-ORM.XML schema.

Bug Description Notes
211298 Provide XML metadata support for existing native EclipseLink annotations RESOLVED - FIXED


Entity

These are Entity definition or Descriptor level configuration features.

Bug Description Notes
211316 Add instantiation-policy support to the EclipseLink-ORM.XML Schema
211306 Add query-key(s) support to the EclipseLink-ORM.XML Schema
211314 Add unary-table sequence support to the EclipseLink-ORM.XML Schema
211327 Add interface(s) support to the EclipseLink-ORM.XML Schema
211322 Add fetch-group(s) support to the EclipseLink-ORM.XML Schema
211329 Add sequencing on non-id attribute(s) support to the EclipseLink-ORM.XML Schema
211319 Add multiple table foreign-key(s) support to the EclipseLink-ORM.XML Schema
211323 Add class extractor support to the EclipseLink-ORM.XML Schema
211330 Add attributes-complete support to the EclipseLink-ORM.XML Schema
211324 Add additional event(s) support to the EclipseLink-ORM.XML Schema Defer
211328 Add history support to the EclipseLink-ORM.XML Schema Defer
211320 Add inheritance-join(s) support to the EclipseLink-ORM.XML Schema Defer
211299 Add PLSQL support to EclipseLink-ORM.XML Schema Defer
211309 Add mapping custom-sql/call support to the EclipseLink-ORM.XML Schema Defer
211310 Add custom-sql/call support to the EclipseLink-ORM.XML Schema Defer
217168 Add descriptor properties support to the EclipseLink-ORM.XML Schema Please add
226515 Add descriptor query policy support to the EclipseLink-ORM.XML Schema (has 8 sub bugs)
211326 Add default-timeout support to the EclipseLink-ORM.XML Schema
226517 Add existence support to the EclipseLink-ORM.XML Schema
226519 Add descriptor query-policy insert-query support to the EclipseLink-ORM.XML Schema
226520 Add descriptor query-policy update-query support to the EclipseLink-ORM.XML Schema
226521 Add descriptor query-policy delete-query support to the EclipseLink-ORM.XML Schema
226523 Add descriptor query policy does-exist-query support to the EclipseLink-ORM.XML Schema 211325 closed as duplicate
226525 Add descriptor query-policy read-object-query support to the EclipseLink-ORM.XML Schema
226526 Add descriptor query-policy read-all-query support to the EclipseLink-ORM.XML Schema
222622 Add XML file sequence support to the EclipseLink-ORM.XML Schema
222295 add read-subclasses-on-queries support to the EclipseLink-ORM.XML Schema

211315: Copy Policy

The copy policy can be configured with one of the following approaches.

Instantiation Copy Policy

@InstantiationCopyPolicy
<instantiation-copy-policy/>

Custom Copy Policy

User provided class name implementing CopyPolicy 

@CopyPolicy("foo.Bar")
<copy-policy policy-class="foo.Bar"/>

Clone Copy Policy

@CloneCopyPolicy(method="myClone")
 
@CloneCopyPolicy(method="myClone", workingCopyMethod="myWorkingCopyClone")
 
@CloneCopyPolicy(workingCopyMethod="myWorkingCopyClone")
<clone-copy-policy type="copy" method="myClone"
workingCopyMethod="myWorkingCopyClone"/>
 
<clone-copy-policy type="copy" workingCopyMethod="myWorkingCopyClone"/>
 
<clone-copy-policy type="copy" method="myClone"/>

Mappings

The following are the outstanding mapping bugs:

Bug Description Notes
217164 Property get/set attribute access using custom methods ASSIGNED
211301 Add aggregate-collection mapping support to the EclipseLink-ORM.XML Schema ASSIGNED
211305 Add XMLType or data-type support to the EclipseLink-ORM.XML Schema
211311 Add mapping selection-criteria support to the EclipseLink-ORM.XML Schema
211312 Add query sequence support to the EclipseLink-ORM.XML Schema
211317 Add additional-join support to the EclipseLink-ORM.XML Schema
211318 Add multiple table join support to the EclipseLink-ORM.XML Schema
211331 Add target-join-column support to the EclipseLink-ORM.XML Schema
211332 Add primary-key element to allow given column support to the EclipseLink-ORM.XML Schema
217168 Add mapping's properties support to the EclipseLink-ORM.XML Schema
224704 need orm.xml support for different indirection policies and types
224634 OneToOnes targeting non id fields, and foreign target relationshipds
225427 need to support read-only, unidirectional ManyToMany mappings
215836 Correct ReturningPolicy support for the EclipseLink-ORM.XML Schema
221876 Add structure support to EclipseLink-ORM.XML Schema

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.

211300: Transformation Mapping

@Transformation(fetch=FecthType.LAZY, optional="true")
@ReadTransformer(class=package.MyNormalHoursTransformer.class)
@WriteTranformers({
   @WriteTranformer(column=@Column(name="START_TIME"), 
      method="getStartDate"),
   @WriteTranformer(column=@Column(name="END_TIME"), 
      class=package.MyTimeTransformer.class)
})
@Mutable
@ReturnUpdate
@Access(AccessType.PROPERTY)
@AccessMethods(get="getNormalHours", set="setNormalHours")
@Properties({
   @Property(name="x", value="y")
})

And in XML: 

<transformation name="normalHours" fetch="LAZY" optional="true">
     <read-transformer method="buildNormalHours"/>
     <write-transformer method="getStartTime">
             <column name="START_TIME"/>
     </write-transformer>
     <write-transformer class="package.MyTimeTransformer">
             <column name="END_TIME"/>
     </write-transformer>
     <mutable/>
     <return-update/>
     <access type="PROPERTY"/>
     <access-methods get="getNormalHours" set="setNormalHours"/>
     <properties>
        <property name="x" value="y"/>
     </properties>
</transformation>

211304: Class Instance Converter

Enables the configuration of ClassInstanceConverter which allows a class name, stored in the database, to be converter to and from a new instance of the specific class. 

@Basic
@Convert("class-instance")
public AddressType getType(){
    return type;
}
<basic name="type">
    <convert>class-instance</convert>
</basic>

211302: Variable 1-1 Mapping

@VariableOneToOne(
    cascade={ALL},
    fetch=LAZY,
    discriminatorColumn=@DiscriminatorColumn(name="CONTACT_TYPE"),
    discriminatorClasses={
        @DiscriminatorClass(discriminator="E", value="Email.class"), 
        @DiscriminatorClass(discriminator="P", value="Phone.class")
    }
}
@JoinColumn(name="CONTACT_ID", referencedColumnName="C_ID")
@PrivateOwned
@JoinFetch(INNER)
public Contact getContact() {
    return contact;
}
<variable-one-to-one name="contact" fetch="LAZY">
    <cascade>
        <cascade-all/>
    </cascade>
    <discriminator-column name="CONTACT_TYPE"/>
    <discriminator-class discriminator="E" value="Email.class"/>
    <discriminator-class discriminator="P" value="Phone.class"/>
    <join-column name="CONTACT_ID" referenced-column-name="C_ID"/>
    <private-owned/>
    <join-fetch>INNER</join-fetch>
</variable-one-to-one>

Other Issues

The following bugs also affect the full completeness of this functionality.

Bug Description Notes
226717 Add database-login metadata support to the EclipseLink-ORM.XML Schema
218082 Provide EclipseLink Project to XMLEntityMappings conversion tool
218084 Implement metadata merging functionality between mapping files
200043 Migration from Oracle TopLink metadata

Resolved Issues

The following bugs originally filed will be deferred from the 1.0 release or will not be addressed.

Bug Description Notes
211303 Add serialized converter support to the EclipseLink-ORM.XML Schema WONT FIX - already covered by JPA

Open Issues

We need to verify that the following topics to ensure these are accessible as JPA extensions

  • WrapperPolicy: EclipseLink-ORM.XML

Design Constraints

Expanding our feature set with the new ORM.xml schema will not proceed till our OX solution has been implemented. After that, functinality bugs may be processed and prioritized for implementation as deemed necessary.

Maintainability

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

GUI

JPA configurations 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 have the option to be written out to the EclipseLink-ORM.XML schema format. Until the EclipseLink-ORM.XML schema supports the full feature set from the existing EclipseLink deployment XML schema, this will allow users to maintain all their mappings and configurations.

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
1 Group Should we allow multiple entities to be defined across multiple mapping files. That is, not only in the eclipselink-orm.xml where users can extend their entity definitions from other persistence unit mapping files.
2 Group For catalog, schema and access (from entity-mappings which are file defaults) should they apply to overlayed metadata in the eclipselink-orm.xml or apply only to entities with a full definition in the eclipselink-orm.xml file?

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
1 Where do we draw the line on overlaying EclipseLink ORM based schema files over the existing JPA orm and mapping files? Override and merge rules have been outlined.
2 Will the writing API be enhanced to support multiple file generation for custom granularity? NO, the file writing will continue to be single file write-out.
3 Will the writing API be enhanced to support writing out the common JPA ORM.XML content into standard ORM.XML file(s)? NO, the file writing will continue to be single file write-out.
4 JPA + Oracle TopLink loading is currently not supported. That is, user's cannot load JPA against an existing Oracle TopLink server session, they are mutually exclusive. Do we want to introduce this functionality? NO, functionality currently will remain the same.
5 Define candidate list of features that must be added during this process and file bugs for additional capabilities to be added later BUG list for additional features has been added. It should continue to grow and this document should be updated as new features are identified.

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.

  • Enhance the file write-out capabilities.
Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/Development/200040/FunctionalSpec&oldid=92036"

This page was last modified 14:37, 11 April 2008 by Eclipsepedia anonymous user Unnamed Poltroon.

Back to the top