Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "EclipseLink/DesignDocs/277920"

Line 158: Line 158:
 
|}
 
|}
  
==== xs:all vs. xs: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:03, 10 November 2009

Design Specification: OXM XSD

ER 277920

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 JPA XSD

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:

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.

Back to the top