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/DesignDocs/277920"
Line 139: | Line 139: | ||
| xml-bidirectional | | xml-bidirectional | ||
|} | |} | ||
− | |||
The following table outlines the Java Enums that map to XML Enums | The following table outlines the Java Enums that map to XML Enums | ||
Line 157: | Line 156: | ||
| xml-ns-form | | xml-ns-form | ||
|} | |} | ||
− | |||
==== all vs. sequence ==== | ==== 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. | 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 ==== | ==== Schema file ==== |
Revision as of 17:04, 10 November 2009
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 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 |
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.