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.
Difference between revisions of "EclipseLink/Development/200040/FunctionalSpec"
(→EclipseLink-ORM.XML Override and Merging) |
(→EclipseLink-ORM.XML Override and Merging) |
||
Line 146: | Line 146: | ||
Override Rules | Override Rules | ||
+ | |||
+ | ===== persistence-unit-metadata override and merging rules ===== | ||
+ | |||
+ | Currently a persistence-unit-metadata specification is to be defined in one and only one mapping file and is 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. | ||
+ | |||
{|{{BMTableStyle}} | {|{{BMTableStyle}} | ||
|-{{BMTHStyle}} | |-{{BMTHStyle}} | ||
Line 151: | Line 156: | ||
! Override/Merge | ! Override/Merge | ||
! Description | ! Description | ||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
| xml-mapping-metadata-complete | | xml-mapping-metadata-complete | ||
Line 181: | Line 182: | ||
|} | |} | ||
+ | ===== entity-mappings override and merging rules ===== | ||
{|{{BMTableStyle}} | {|{{BMTableStyle}} | ||
|-{{BMTHStyle}} | |-{{BMTHStyle}} | ||
− | ! entity-mappings/ | + | ! entity-mappings/ |
! Override/Merge | ! Override/Merge | ||
! Description | ! Description | ||
|- | |- | ||
− | | | + | | package |
| None | | None | ||
| The package subelement specifies the package of the classes listed within the subelements and attributes of the same mapping file only. The package subelement is overridden if the fully qualified class name is specified for a class and the two disagree. | | The package subelement specifies the package of the classes listed within the subelements and attributes of the same mapping file only. The package subelement is overridden if the fully qualified class name is specified for a class and the two disagree. | ||
|- | |- | ||
− | | | + | | catalog |
| None | | None | ||
| The catalog applies only to the entities listed within the same mapping file that are not part of an override to another mapping file. Otherwise, the use of the catalog within this mapping file remains the same as described in the JPA spec. | | The catalog applies only to the entities listed within the same mapping file that are not part of an override to another mapping file. Otherwise, the use of the catalog within this mapping file remains the same as described in the JPA spec. | ||
|- | |- | ||
− | | | + | | schema |
| None | | None | ||
| The schema applies only to the entities listed within the same mapping file that are not part of an override to another mapping file. Otherwise, the use of the schema within this mapping file remains the same as described in the JPA spec. | | The schema applies only to the entities listed within the same mapping file that are not part of an override to another mapping file. Otherwise, the use of the schema within this mapping file remains the same as described in the JPA spec. | ||
|- | |- | ||
− | | | + | | access |
| None | | None | ||
| The access applies only to the entities listed within the same mapping file that are not part of an override to another mapping file. Otherwise, the use of the access within this mapping file remains the same as described in the JPA spec. | | The access applies only to the entities listed within the same mapping file that are not part of an override to another mapping file. Otherwise, the use of the access within this mapping file remains the same as described in the JPA spec. | ||
|- | |- | ||
− | | | + | | sequence-generator |
| Full | | Full | ||
| A sequence-generator is unique by name. A sequence-generator with the same named defined in another mapping file will be overriden. | | A sequence-generator is unique by name. A sequence-generator with the same named defined in another mapping file will be overriden. | ||
|- | |- | ||
− | | | + | | table-generator |
| Full | | Full | ||
| A table-generator is unique by name. A table-generator with the same named defined in another mapping file will be overriden. | | A table-generator is unique by name. A table-generator with the same named defined in another mapping file will be overriden. | ||
|- | |- | ||
− | | | + | | named-query |
| Full | | Full | ||
| A named-query is unique by name. A named-query with the same named defined in another mapping file will be overriden. | | A named-query is unique by name. A named-query with the same named defined in another mapping file will be overriden. | ||
|- | |- | ||
− | | | + | | named-native-query |
| Full | | Full | ||
| A named-query is unique by name. A named-query with the same named defined in another mapping file will be overriden. | | A named-query is unique by name. A named-query with the same named defined in another mapping file will be overriden. | ||
|- | |- | ||
− | | | + | | sql-result-set-mapping |
| Full | | Full | ||
| 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 overriden. | | 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 overriden. | ||
+ | |} | ||
+ | |||
+ | ===== mapped-superclass override and merging rules ===== | ||
+ | |||
+ | {|{{BMTableStyle}} | ||
+ | |-{{BMTHStyle}} | ||
+ | ! entity-mappings/mapped-superclass | ||
+ | ! Override/Merge | ||
+ | ! Description | ||
|- | |- | ||
| entity-mappings/mapped-superclass | | entity-mappings/mapped-superclass | ||
| Mapping level | | Mapping level | ||
| A mapped-superclass can be defined wholely or may be defined so as to provide extensions to a mapped superclass from another mapping file. | | A mapped-superclass can be defined wholely or may be defined so as to provide extensions to a mapped superclass from another mapping file. | ||
+ | |||
+ | ===== entity override and merging rules ===== | ||
+ | |||
+ | {|{{BMTableStyle}} | ||
+ | |-{{BMTHStyle}} | ||
+ | ! entity-mappings/entity | ||
+ | ! Override/Merge | ||
+ | ! Description | ||
|- | |- | ||
| entity-mappings/entity | | entity-mappings/entity | ||
Line 232: | Line 251: | ||
| An entity can be defined wholely or may be defined so as to provide extensions to a mapped superclass from another mapping file. | | An entity can be defined wholely or may be defined so as to provide extensions to a mapped superclass from another mapping file. | ||
|- | |- | ||
− | | | + | | table |
| Full | | Full | ||
| Any table specification assumes complete specification, including table, secondary-table and primary-key-join-column | | Any table specification assumes complete specification, including table, secondary-table and primary-key-join-column | ||
|- | |- | ||
− | | | + | | secondary-table |
| Full | | Full | ||
| Any table specification assumes complete specification, including table, secondary-table and primary-key-join-column | | Any table specification assumes complete specification, including table, secondary-table and primary-key-join-column | ||
|- | |- | ||
− | | | + | | primary-key-join-column |
| Full | | Full | ||
| Any table specification assumes complete specification, including table, secondary-table and primary-key-join-column | | Any table specification assumes complete specification, including table, secondary-table and primary-key-join-column | ||
Line 255: | Line 274: | ||
| ? | | ? | ||
| | | | ||
− | |- | + | |} |
− | | entity-mappings/embeddable | + | |
+ | ===== embeddable override and merging rules ===== | ||
+ | |||
+ | {|{{BMTableStyle}} | ||
+ | |-{{BMTHStyle}} | ||
+ | ! entity-mappings/entity | ||
+ | ! Override/Merge | ||
+ | ! Description | ||
+ | |- entity-mappings/embeddable | ||
| Mapping level | | Mapping level | ||
| An embeddable can be defined wholely or may be defined so as to provide extensions to a mapped superclass from another mapping file. | | An embeddable can be defined wholely or may be defined so as to provide extensions to a mapped superclass from another mapping file. |
Revision as of 15:43, 27 November 2007
Contents
- 1 Functional Specification: New Native Object-Relational Mapping XML
- 2 Document History
- 3 Project overview
- 4 Concepts
- 5 Requirements
- 5.1 EclipseLink-ORM.XML XSD
- 5.2 EclipseLink-ORM.XML Processing
- 5.2.1 EclipseLink-ORM.XML Locations
- 5.2.1.1 Default Locations
- 5.2.1.2 EclipseLink-ORM.XML Override and Merging
- 5.2.1.2.1 persistence-unit-metadata override and merging rules
- 5.2.1.2.2 entity-mappings override and merging rules
- 5.2.1.2.3 mapped-superclass override and merging rules
- 5.2.1.2.4 entity override and merging rules
- 5.2.1.2.5 embeddable override and merging rules
- 5.2.1.2.6 Use case 1
- 5.2.1.2.7 Use case 2
- 5.2.1.2.8 Use case 3
- 5.2.1.2.9 Use case 4
- 5.2.1.2.10 Use case 5
- 5.2.2 File Granularity
- 5.2.3 EclipseLink-ORM.XML in place of JPA's ORM.XML
- 5.2.4 API access to EclipseLink-ORM.XML
- 5.2.5 Backwards Compatibility
- 5.2.1 EclipseLink-ORM.XML Locations
- 5.3 EclipseLink-ORM.XML Writing
- 6 Functionality
- 7 Design Constraints
- 8 Maintainability
- 9 GUI
- 10 Config files
- 11 Documentation
- 12 Open Issues
- 13 Decisions
- 14 Future Considerations
Functional Specification: New Native Object-Relational Mapping XML
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-26 | Guy Pelletier | Further 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:
- 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.
- 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).
- Must embrace configuration by exception so only scope and non-default configurations need to be specified.
- Must embrace minimal config, ORM.XML alignment for overrides, and complete configuration without any JPA annotations or XML.
- 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.
- 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 JPA XSD. Currently no elements as a whole are required only certain attributes within specified elements are required in the ORM.XML schema. 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:
- 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).
- Expand EclipseLink’s feature availability within the EclipseLink-ORM.XML beyond what is currently available.
- See Open Issues section #5
- Support multiple metadata loading schemes
- JPA only (annotations and XML)
- EclipseLink Native only (native annotations and XML)
- Oracle TopLink only: Support reading in and using Orcale TopLink's 11gR1 and 10.1.3 XML configuration files
- JPA + EclipseLink Native
- JPA + Oracle TopLink – Currently not supported, adding to the Open Issues section. User's cannot load JPA against an existing Oracle TopLink server-session/project. They are mutually exclusive.
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:
- Default location
- META-INF/eclipselink-orm.xml
- META-INF/orm.xml (in place of JPA's ORM.XML. Note: This most certainly will not be portable)
- Referenced as persistence unit mapping file in persistence.xml
- 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.
EclipseLink-ORM.XML Override and Merging
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 they 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 they 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 table outlines 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.
Override Rules
persistence-unit-metadata override and merging rules
Currently a persistence-unit-metadata specification is to be defined in one and only one mapping file and is 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 | Override/Merge | Description |
---|---|---|
xml-mapping-metadata-complete | Override and merge | Any xml-mapping-unit-metadata setting will override an existing setting or merge one |
persistence-unit-defaults/schema | Override and merge | Any schema setting will override an existing setting or merge one |
persistence-unit-defaults/catalog | Override and merge | Any catalog setting will override an existing setting or merge one |
persistence-unit-defaults/access | Override and merge | Any access setting will override an existing setting or merge one |
entity-mappings/persistence-unit-metadata/persistence-unit-defaults/cascade-persist | Override and merge | Any cascade-persist setting will override an existing setting or merge one |
entity-mappings/persistence-unit-metadata/persistence-unit-defaults/entity-listeners | Override and merge | Any listeners defined here will override existing listeners and merge new ones |
entity-mappings override and merging rules
entity-mappings/ | Override/Merge | Description |
---|---|---|
package | None | The package subelement specifies the package of the classes listed within the subelements and attributes of the same mapping file only. The package subelement is overridden if the fully qualified class name is specified for a class and the two disagree. |
catalog | None | The catalog applies only to the entities listed within the same mapping file that are not part of an override to another mapping file. Otherwise, the use of the catalog within this mapping file remains the same as described in the JPA spec. |
schema | None | The schema applies only to the entities listed within the same mapping file that are not part of an override to another mapping file. Otherwise, the use of the schema within this mapping file remains the same as described in the JPA spec. |
access | None | The access applies only to the entities listed within the same mapping file that are not part of an override to another mapping file. Otherwise, the use of the access within this mapping file remains the same as described in the JPA spec. |
sequence-generator | Full | A sequence-generator is unique by name. A sequence-generator with the same named defined in another mapping file will be overriden. |
table-generator | Full | A table-generator is unique by name. A table-generator with the same named defined in another mapping file will be overriden. |
named-query | Full | A named-query is unique by name. A named-query with the same named defined in another mapping file will be overriden. |
named-native-query | Full | A named-query is unique by name. A named-query with the same named defined in another mapping file will be overriden. |
sql-result-set-mapping | Full | 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 overriden. |
mapped-superclass override and merging rules
entity-mappings/mapped-superclass | Override/Merge | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
entity-mappings/mapped-superclass | Mapping level | A mapped-superclass can be defined wholely or may be defined so as to provide extensions to a mapped superclass from another mapping file.
entity override and merging rules
embeddable override and merging rules
Use case 1
Use case 2
Use case 3
Use case 4
Use case 5
File GranularityDevelopers 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 ORM.XMLThe 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.XMLThe EclipseLink-ORM.XML file will be usable anywhere the previous deployment XML file can be used:
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 CompatibilityEclipseLink 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 WritingThe 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.
Writing Open Issues:
FunctionalityThe EclipseLink-ORM.XML schema will be built from the existing 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.
Note:
Milestone a
Milestone b
Milestone c
Milestone d
Milestone e
Milestone f
Milestone g
Milestone h
Milestone i
Milestone j
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 ConstraintsExpanding 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. MaintainabilityThe maintainability of this project is greatly eased by updating our current JPA metadata processing to use our OX technology. GUIJPA 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 filesThe 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. DocumentationAny documents that outline specific xml configurations should be listed here. Open IssuesThis section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.
DecisionsThis section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.
Future ConsiderationsDuring 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. |