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.
EclipseLink/DesignDocs/277920
Contents
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 ER 293925 |
Project overview
Goals:
- Support a limited number 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
The metadata that will be available in EclipseLink 2.0 is outlined 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 external metadata 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. The the following MOXy mappings will be utilized:
- Direct
- Direct Collection
- Composite Object
- Composite Collection
- Provide support for nested data. The the following MOXy mappings will be utilized:
- Phase #4 – Any/Choice Content
- Provide support for wild card data. The the following MOXy mappings will be utilized:
- Any
- Any Collection
- Any Attribute
- Provide support for wild card data. The the following MOXy mappings will be utilized:
- Phase #5 – Reference Mappings
- Provide support for key based mappings. The the following MOXy mappings will be utilized:
- Object Reference
- Collection Reference
- Provide support for key based mappings. The the following MOXy mappings will be utilized:
Design / Functionality
XML Bindings
A given XML metadata bindings file will correspond to a single package. This association is made by using the package name for the key in the properties map that is passed in to the JAXBContext. See below for information on boot strapping the JAXBContext. The bindings file may contain information that applies to the entire package, as well as class-specific information. The java-type
element is used for a java class. Each java-type
may have a number of attributes and sub-elements set (refer to the XML Schema above for more information) as well as zero or more java-attributes
. A java-attribute
corresponds to a property (field/method). In order to handle various settings applicable to a given property, a number of java-attribute
extensions exist:
- xml-java-type-adapter
- xml-transient
- xml-any-attribute
- xml-attribute
- xml-any-element
- xml-element
- xml-value
XML Schema
Naming Convention
The XML names are based directly on the corresponding annotation name. The annotation name is lower cased, and hyphens ('-') are used as separators between each word in the name. For example, the annotation XmlJavaTypeAdapter
would correspond to xml-java-type-adapter
in XML.
Annotations to XML
The following table outlines the annotations that map to global elements:
Annotation | Global Element |
---|---|
XmlElement | xml-element |
XmlSchema | xml-schema |
XmlJavaTypeAdapter | xml-java-type-adapter |
XmlJavaTypeAdapters | xml-java-type-adapters |
XmlTransient | xml-transient |
XmlType | xml-type |
XmlRootElement | xml-root-element |
XmlSeeAlso | xml-see-also |
XmlAnyAttribute | xml-any-attribute |
XmlAttribute | xml-attribute |
XmlAnyElement | xml-any-element |
XmlElement | xml-element |
XmlElementWrapper | xml-element-wrapper |
XmlValue | xml-value |
XmlBidirectional (MOXy) | xml-bidirectional |
The following table outlines the Java Enums that map to XML Enums
Java Enum | XML Enum |
---|---|
XmlAccessOrder | xml-access-order |
XmlAccessType | xml-access-type |
XmlNsForm | xml-ns-form |
XML Bindings
A given XML metadata bindings file will correspond to a single package. This association is made by using the package name for the key in the properties map that is passed in to the JAXBContext. See below for information on boot strapping the JAXBContext. The bindings file may contain package level overrides, such as xml-schema
, xml-java-type-adapters
, etc., and class overrides. The java-type
element is used for a java class. Each java-type
may have a number of attributes and sub-elements set (see the XML Schema below) as well as zero or more java-attribute
declarations. More...
all vs. sequence
Where applicable xs:all is used instead of xs:sequence, such that specific ordering is not required. This is done to avoid placing an unnecessary requirement on the user.
Schema file
The XML schema that will be supported in EclipseLink 2.0 follows:
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" targetNamespace="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="xml-bindings"> <xs:complexType> <xs:all> <xs:element ref="xml-schema" /> <xs:element ref="xml-java-type-adapters" /> <xs:element name="java-types"> <xs:complexType> <xs:sequence> <xs:element ref="java-type" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> </xs:all> <xs:attribute name="xml-accessor-type" type="xml-access-type" default="PUBLIC_MEMBER" /> <xs:attribute name="xml-accessor-order" type="xml-access-order" default="UNDEFINED" /> </xs:complexType> </xs:element> <xs:element name="java-type"> <xs:complexType> <xs:all> <xs:element ref="xml-type" /> <xs:element ref="xml-root-element" /> <xs:element ref="xml-see-also" /> <xs:element ref="xml-java-type-adapter" /> <xs:element name="java-attributes"> <xs:complexType> <xs:sequence> <xs:element ref="java-attribute" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> </xs:all> <xs:attribute name="name" type="xs:string" /> <xs:attribute name="xml-transient" type="xs:boolean" default="false" /> <xs:attribute name="xml-customizer" type="xs:string" /> <xs:attribute name="xml-accessor-type" type="xml-access-type" default="PUBLIC_MEMBER" /> <xs:attribute name="xml-accessor-order" type="xml-access-order" default="UNDEFINED" /> </xs:complexType> </xs:element> <xs:element name="java-attribute" type="java-attribute" /> <xs:complexType name="java-attribute" abstract="true"> <xs:attribute name="java-attribute" type="xs:string" /> </xs:complexType> <!-- Enums --> <xs:simpleType name="xml-access-order"> <xs:restriction base="xs:string"> <xs:enumeration value="ALPHABETICAL" /> <xs:enumeration value="UNDEFINED" /> </xs:restriction> </xs:simpleType> <xs:simpleType name="xml-access-type"> <xs:restriction base="xs:string"> <xs:enumeration value="FIELD" /> <xs:enumeration value="NONE" /> <xs:enumeration value="PROPERTY" /> <xs:enumeration value="PUBLIC_MEMBER" /> </xs:restriction> </xs:simpleType> <xs:simpleType name="xml-ns-form"> <xs:restriction base="xs:string"> <xs:enumeration value="UNQUALIFIED" /> <xs:enumeration value="QUALIFIED" /> <xs:enumeration value="UNSET" /> </xs:restriction> </xs:simpleType> <!-- @Target(value=PACKAGE) --> <xs:element name="xml-schema"> <xs:complexType> <xs:sequence> <xs:element name="xml-ns" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:attribute name="namespace-uri" type="xs:string" /> <xs:attribute name="prefix" type="xs:string" /> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="attribute-form-default" type="xml-ns-form" default="UNSET" /> <xs:attribute name="element-form-default" type="xml-ns-form" default="UNSET" /> <xs:attribute name="location" type="xs:string" /> <xs:attribute name="namespace" type="xs:string" /> </xs:complexType> </xs:element> <xs:element name="xml-java-type-adapters"> <xs:complexType> <xs:sequence> <xs:element ref="xml-java-type-adapter" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> <!-- @Target(value={PACKAGE,FIELD,METHOD,TYPE,PARAMETER}) --> <xs:element name="xml-java-type-adapter" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute"> <xs:attribute name="value" type="xs:string" /> <xs:attribute name="type" type="xs:string" default="javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter.DEFAULT" /> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <!-- @Target(value={FIELD,METHOD,TYPE}) --> <xs:element name="xml-transient" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute" /> </xs:complexContent> </xs:complexType> </xs:element> <!-- @Target(value=TYPE) --> <xs:element name="xml-type"> <xs:complexType> <xs:attribute name="name" type="xs:string" default="##default" /> <xs:attribute name="namespace" type="xs:string" default="##default" /> <xs:attribute name="prop-order"> <xs:simpleType> <xs:list itemType="xs:string" /> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element> <xs:element name="xml-root-element"> <xs:complexType> <xs:attribute name="name" type="xs:string" default="##default" /> <xs:attribute name="namespace" type="xs:string" default="##default" /> </xs:complexType> </xs:element> <xs:element name="xml-see-also"> <xs:simpleType> <xs:list itemType="xs:string" /> </xs:simpleType> </xs:element> <!-- @Target(value={FIELD,METHOD}) --> <xs:element name="xml-any-attribute" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="xml-attribute" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute"> <xs:all> <xs:element ref="xml-java-type-adapter" /> <xs:element ref="xml-bidirectional" /> </xs:all> <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:attribute name="xml-id" type="xs:boolean" default="false" /> <xs:attribute name="xml-idref" type="xs:boolean" default="false" /> <xs:attribute name="xml-list" type="xs:boolean" default="false" /> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="xml-any-element" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute"> <xs:all> <xs:element ref="xml-java-type-adapter" /> </xs:all> <xs:attribute name="xml-mixed" type="xs:boolean" default="false" /> <xs:attribute name="lax" type="xs:boolean" default="false" /> <xs:attribute name="dom-handler" type="xs:string" default="javax.xml.bind.annotation.W3CDomHandler" /> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="xml-element" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute"> <xs:all> <xs:element ref="xml-element-wrapper" /> <xs:element ref="xml-java-type-adapter" /> <xs:element ref="xml-bidirectional" /> </xs:all> <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:attribute name="xml-id" type="xs:boolean" default="false" /> <xs:attribute name="xml-idref" type="xs:boolean" default="false" /> <xs:attribute name="xml-list" type="xs:boolean" default="false" /> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="xml-element-wrapper"> <xs:complexType> <xs:attribute name="name" type="xs:string" default="##default" /> <xs:attribute name="namespace" type="xs:string" default="##default" /> <xs:attribute name="nillable" type="xs:boolean" default="false" /> <xs:attribute name="required" type="xs:boolean" default="false" /> </xs:complexType> </xs:element> <xs:element name="xml-value" substitutionGroup="java-attribute"> <xs:complexType> <xs:complexContent> <xs:extension base="java-attribute" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="xml-bidirectional"> <xs:complexType> <xs:attribute name="target-attribute" type="xs:string" /> </xs:complexType> </xs:element> </xs:schema>
Boot Strapping
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); 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);
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.