Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/DesignDocs/277920"
< EclipseLink | DesignDocs
(→Project overview) |
|||
| Line 24: | Line 24: | ||
Goals: | Goals: | ||
* Support JAXB 2.1 annotations via XML external metadata | * Support JAXB 2.1 annotations via XML external metadata | ||
| − | |||
| − | |||
== Concepts == | == Concepts == | ||
| Line 51: | Line 49: | ||
=== EclipseLink MOXy Metadata === | === EclipseLink MOXy Metadata === | ||
| − | At a minimum the metadata available in EclipseLink 2. | + | At a minimum the metadata available in EclipseLink 2.0 must be available in the new format (see below). |
| − | == | + | == Design Phases == |
=== JAXB 2.1 annotation support via XML external metadata === | === JAXB 2.1 annotation support via XML external metadata === | ||
| Line 90: | Line 88: | ||
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase10 Phase #10 – XML Registry] | * [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase10 Phase #10 – XML Registry] | ||
** Provide support for ObjectFactory methods | ** Provide support for ObjectFactory methods | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
== Design / Functionality == | == Design / Functionality == | ||
| Line 672: | Line 112: | ||
==== Specifying the Externalized Metadata File ==== | ==== Specifying the Externalized Metadata File ==== | ||
| − | + | The externalized metadata file (one per package) can be passed in through a property when creating the JAXBContext. | |
<source lang="java"> | <source lang="java"> | ||
| − | + | InputStream employeeExternalizedMetadata = | |
| − | + | aClassLoader.getResourceAsStream("org/example/employee/metadata.xml"; | |
| − | + | InputStream customerExternalizedMetadata = | |
| − | < | + | aClassLoader.getResourceAsStream("org/example/customer/metadata.xml"; |
| − | + | HashMap<String, Source> metadataSourceMap = new HashMap<String, Source>(); | |
| − | + | metadataSourceMap.put("org.example.employee", new StreamSource(employeeExternalizedMetadata)); | |
| + | metadataSourceMap.put("org.example.customer", new StreamSource(customerExternalizedMetadata)); | ||
| + | Map<String, Map<String, Source>> properties = new HashMap<String, Map<String, Source>>(); | ||
| + | properties.put("eclipselink-oxm-xml", metadataSourceMap); | ||
<source lang="java"> | <source lang="java"> | ||
| Line 686: | Line 129: | ||
</source> | </source> | ||
| − | + | Following is an example of how to pass in the property when creating the JAXBContext based on an array of classes: | |
<source lang="java"> | <source lang="java"> | ||
| − | Class[] classes = new Class[ | + | Class[] classes = new Class[2]; |
classes[0] = Customer.class; | classes[0] = Customer.class; | ||
classes[1] = Employee.class; | classes[1] = Employee.class; | ||
| − | |||
JAXBContext.newInstance(classes, properties); | JAXBContext.newInstance(classes, properties); | ||
</source> | </source> | ||
Revision as of 12:44, 9 November 2009
Contents
- 1 Design Specification: OXM XSD
- 1.1 Document History
- 1.2 Project overview
- 1.3 Concepts
- 1.4 Requirements
- 1.5 Design Constraints
- 1.6 Design Phases
- 1.7 Design / Functionality
- 1.8 Testing
- 1.9 API
- 1.10 GUI
- 1.11 Config files
- 1.12 Documentation
- 1.13 Open Issues
- 1.14 Decisions
- 1.15 Future Considerations
Design Specification: OXM XSD
Document History
| Date | Author | Version Description & Notes |
|---|---|---|
| 2009/05/26 | Blaise Doughan | Skeleton |
| 2009/11/09 | David McCann | Added information pertaining to JAXB annotation support design phases. Moving phases 6 - 10, WebService support and OXM mapping support to design document for Enhancement# 293925 |
Project overview
Goals:
- Support JAXB 2.1 annotations via XML external metadata
Concepts
None to mention.
Requirements
The following sections will expand the goals of this project into more concrete requirements.
Design Constraints
JAXB Annotations
The XML should have the same feel as the JAXB annotations.
javax.xml.bind.annotation Javadoc
EclipseLink JPA Metadata
The XML should have the same feel as the equivalent XML for EclipseLink JPA
EclipseLink MOXy Metadata
At a minimum the metadata available in EclipseLink 2.0 must be available in the new format (see below).
Design Phases
JAXB 2.1 annotation support via XML external metadata
This support will be added as outlined in the following phases:
- Phase #1 – Bootstrapping
- Use eclipselink-oxm.xml file to provide list of classes
- Allow basic schema to be generated
- Phase #2 – High Level Metadata
- Provide core type metadata
- Phase #3 – Containment Mappings
- Provide support for nested data via the following mappings:
- Direct
- Direct Collection
- Composite Object
- Composite Collection
- Provide support for nested data via the following mappings:
- Phase #4 – Any/Choice Content
- Provide support for wild card data via the following mappings:
- Any
- Any Collection
- Any Attribute
- Provide support for wild card data via the following mappings:
- Phase #5 – Reference Mappings
- Provide support for key based mappings via the following mappings:
- Object Reference
- Collection Reference
- Provide support for key based mappings via the following mappings:
- Phase #6 – Substitution Groups
- Provide support for substitution groups via the following mappings:
- Choice
- Choice Collection
- Provide support for substitution groups via the following mappings:
- Phase #7 – Schema Customization
- Allow customized mapping to an XML Schema built in type
- Phase #8 – Enums
- Provide support for Java Enums
- Phase #9 – Attachments
- Provide support for WebService attachments
- Phase #10 – XML Registry
- Provide support for ObjectFactory methods
Design / Functionality
Boot Strapping
Default Behaviour
When creating a JAXBContext an eclipselink-oxm.xml file will be looked for, for each item on the context path.
JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader);
The ClassLoader parameter will be used to find the eclipselink-oxm.xml file in a manner similar to:
InputStream externalizedMetadata1 = aClassLoader.getResourceAsStream("org/example/customer/eclipselink-oxm.xml"; InputStream externalizedMetadata2 = aClassLoader.getResourceAsStream("org/example/employee/eclipselink-oxm.xml";
Specifying the Externalized Metadata File
The externalized metadata file (one per package) can be passed in through a property when creating the JAXBContext.
InputStream employeeExternalizedMetadata = aClassLoader.getResourceAsStream("org/example/employee/metadata.xml"; InputStream customerExternalizedMetadata = aClassLoader.getResourceAsStream("org/example/customer/metadata.xml"; HashMap<String, Source> metadataSourceMap = new HashMap<String, Source>(); metadataSourceMap.put("org.example.employee", new StreamSource(employeeExternalizedMetadata)); metadataSourceMap.put("org.example.customer", new StreamSource(customerExternalizedMetadata)); Map<String, Map<String, Source>> properties = new HashMap<String, Map<String, Source>>(); properties.put("eclipselink-oxm-xml", metadataSourceMap); <source lang="java"> JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader, properties);
Following is an example of how to pass in the property when creating the JAXBContext based on an array of classes:
Class[] classes = new Class[2]; classes[0] = Customer.class; classes[1] = Employee.class; JAXBContext.newInstance(classes, properties);
Common Mapping Metadata
XML Schema
<xs:complexType name="java-attribute"> <xs:all> <xs:element ref="properties"/> </xs:all> <xs:attribute name="attribute-name" type="xs:string"/> <xs:attribute name="get-method" type="xs:string"/> <xs:attribute name="set-method" type="xs:string"/> <xs:attribute name="read-only" type="xs:boolean" default="false"/> </xs:complexType> <xs:element name="properties"> <xs:complexType> <xs:sequence> <xs:element name="property" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:attribute name="name" type="xs:string"/> <xs:attribute name="value" type="xs:string"/> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element>
XML
<xml-mapping attribute-name="String" read-only="false" get-method="String" set-method="String"> <properties> <property name="String" value="String"/> <property name="String" value="String"/> </properties> </xml-mapping>
Null Policy
XML Schema
<xs:element name="null-policy"> <xs:complexType> <xs:attribute name="set-performed-for-absent-node" type="xs:boolean" default="true"/> <xs:attribute name="null-represented-by-empty-node" type="xs:boolean" default="false"/> <xs:attribute name="null-represented-by-xsi-nil" type="xs:boolean" default="false"/> <xs:attribute name="marshal-null-representation"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="XSI_NIL"/> <xs:enumeration value="ABSENT_NODE"/> <xs:enumeration value="EMPTY_NODE"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element>
XML
<null-policy> <xsi-nil-represents-null>false</xsi-nil-represents-null> <empty-node-represents-null>false</empty-node-represents-null> <null-representation-for-xml>XSI_NIL</null-representation-for-xml> </null-policy>
XML Any Attribute Mapping
Annotations
@XmlAnyAttribute @IncludeNamespaceDeclaration(value=true) @IncludeSchemaInstance(value=true)
XML Schema
<xs:element name="xml-any-attribute-mapping"> <xs:complexType> <xs:complexContent> <xs:extension base="xml-mapping"> <xs:attribute name="include-namespace-declaration" type="xs:boolean"/> <xs:attribute name="include-schema-instance" type="xs:boolean"/> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element>
XML
<xml-any-attribute-mapping attribute-name="String" read-only="false" get-method="String" set-method="String" include-namespace-declaration="true" include-schema-instance="true"> <properties> <property name="String" value="String"/> </properties> </xml-any-attribute-mapping>
XML Attribute
<xs:element name="xml-attribute" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute"> <xs:all> <xs:element ref="xml-schema-type"/> <xs:element ref="xml-java-type-adapter"/> <xs:element ref="null-policy"/> </xs:all> <xs:attribute ref="xml-inline-binary-data"/> <xs:attribute ref="xml-id"/> <xs:attribute ref="xml-idref"/> <xs:attribute ref="xml-attachment-ref"/> <xs:attribute ref="xml-list"/> <xs:attribute ref="xml-mime-type"/> <xs:attribute name="name" type="xs:string" default="##default"/> <xs:attribute name="namespace" type="xs:string" default="##default"/> <xs:attribute name="required" type="xs:boolean" default="false"/> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element>
XML Element
<xs:element name="xml-element" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute"> <xs:all> <xs:element ref="xml-schema-type"/> <xs:element ref="xml-element-wrapper"/> <xs:element ref="xml-java-type-adapter"/> <xs:element ref="null-policy"/> </xs:all> <xs:attribute ref="xml-inline-binary-data"/> <xs:attribute ref="xml-id"/> <xs:attribute ref="xml-idref"/> <xs:attribute ref="xml-attachment-ref"/> <xs:attribute ref="xml-list"/> <xs:attribute ref="xml-mime-type"/> <xs:attribute name="name" type="xs:string" default="##default"/> <xs:attribute name="namespace" type="xs:string" default="##default"/> <xs:attribute name="default-value" type="xs:string"/> <xs:attribute name="nillable" type="xs:boolean" default="false"/> <xs:attribute name="required" type="xs:boolean" default="false"/> <xs:attribute name="type" type="xs:string" default="javax.xml.bind.annotation.XmlElement.DEFAULT"/> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element>
Testing
API
GUI
Config files
Documentation
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 |
|---|---|---|
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 |
|---|---|---|
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.