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

EclipseLink/DesignDocs/293925

Design Specification: MOXy - OXM XSD

ER 293925

Document History

Date Author Version Description & Notes
2009/11/09 David McCann Initial Contribution. The work outlined in this design document is a continuation of the work done for ER 277920

Project overview

Goals:

  • Add additional XML external metadata support to satisfy WebServices requirements
  • Support OXM mappings 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

At a minimum the metadata available in EclipseLink 2.1 must be available in the new format (see below).

High Level Design

XML external metadata support for WebServices

TBD.

OXM mapping support via XML external metadata

The following OXM mappings will be supported via XML external metadata:

  • XML Direct
  • XML Composite Direct Collection
  • XML Composite Object
  • XML Composite Collection
  • XML Object Reference
  • XML Collection Reference
  • XML Binary Data
  • XML Binary Data Collection
  • XML Any Object
  • XML Any Collection
  • XML Fragment
  • XML Fragment Collection
  • XML Choice Object
  • XML Choice Collection
  • XML Transformation
  • XML Any Attribute

XML Direct Mapping

<xml-direct-mapping
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<null-value>String</null-value>
	<converter/>
	<attribute-classification>String</attribute-classification>
	<is-cdata>1</is-cdata>
	<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-direct-mapping>

XML Composite Direct Collection Mapping

<xml-composite-direct-collection-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<value-converter/>
	<value-converter-class>String</value-converter-class>
	<container>
		<collection-type>String</collection-type>
	</container>
	<is-cdata>1</is-cdata>
</xml-composite-direct-collection-mapping>

XML Composite Object Mapping

<xml-composite-object-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<reference-class>String</reference-class>
	<field name="String"/>
	<container-attribute>Text</container-attribute>
	<container-get-method>Text</container-get-method>
	<container-set-method>Text</container-set-method>
	<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>
	<keep-as-element-policy>String</keep-as-element-policy>
</xml-composite-object-mapping>

XML Composite Collection Mapping

<xml-composite-collection-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<reference-class>String</reference-class>
	<field name="String"/>
	<container>
		<collection-type>String</collection-type>
	</container>
	<container-attribute>Text</container-attribute>
	<container-get-method>Text</container-get-method>
	<container-set-method>Text</container-set-method>
	<keep-as-element-policy>String</keep-as-element-policy>
</xml-composite-collection-mapping>

XML Object Reference Mapping

<xml-object-reference-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<reference-class>String</reference-class>
	<allow-null>true</allow-null>
	<field-translations>
		<field-translation>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-translation>
		<field-translation>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-translation>
	</field-translations>
	<source-to-target-key-field-association>
		<field-reference>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-reference>
		<field-reference>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-reference>
	</source-to-target-key-field-association>
	<source-to-target-key-fields>
		<field name="String"/>
		<field name="String"/>
	</source-to-target-key-fields>
</xml-object-reference-mapping>

XML Collection Reference Mapping

<xml-collection-reference-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<reference-class>String</reference-class>
	<allow-null>true</allow-null>
	<field-translations>
		<field-translation>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-translation>
		<field-translation>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-translation>
	</field-translations>
	<source-to-target-key-field-association>
		<field-reference>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-reference>
		<field-reference>
			<source-field name="String"/>
			<target-field name="String"/>
		</field-reference>
	</source-to-target-key-field-association>
	<source-to-target-key-fields>
		<field name="String"/>
		<field name="String"/>
	</source-to-target-key-fields>
	<containerpolicy>
		<collection-type>String</collection-type>
	</containerpolicy>
	<uses-single-node>1</uses-single-node>
</xml-collection-reference-mapping>

XML Binary Data Mapping

<xml-binary-data-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<null-value>String</null-value>
	<converter/>
	<attribute-classification>String</attribute-classification>
	<is-cdata>1</is-cdata>
	<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>
	<is-swa-ref>1</is-swa-ref>
	<mime-type>String</mime-type>
	<should-inline-data>1</should-inline-data>
</xml-binary-data-mapping>

XML Binary Data Collection Mapping

XML Any Object Mapping

<xml-any-object-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<use-xml-root>false</use-xml-root>
	<keep-as-element-policy>String</keep-as-element-policy>
</xml-any-object-mapping>

XML Any Collection Mapping

<xml-any-collection-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<container>
		<collection-type>String</collection-type>
	</container>
	<use-xml-root>false</use-xml-root>
	<keep-as-element-policy>String</keep-as-element-policy>
</xml-any-collection-mapping>

XML Fragment Mapping

<xml-fragment-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<null-value>String</null-value>
	<converter/>
	<attribute-classification>String</attribute-classification>
	<is-cdata>1</is-cdata>
	<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-fragment-mapping>

XML Fragment Collection

<xml-fragment-collection-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<reference-class>String</reference-class>
	<field name="String"/>
	<container>
		<collection-type>String</collection-type>
	</container>
</xml-fragment-collection-mapping>

XML Choice Object Mapping

<xml-choice-object-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field-to-class-association>
		<xml-field name="String">
			<position>0</position>
			<typed-text-field>1</typed-text-field>
			<single-node>1</single-node>
			<schema-type>String</schema-type>
			<schema-type>String</schema-type>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<leaf-element-type>String</leaf-element-type>
		</xml-field>
		<class-name>String</class-name>
	</field-to-class-association>
	<field-to-class-association>
		<xml-field name="String">
			<position>0</position>
			<typed-text-field>1</typed-text-field>
			<single-node>1</single-node>
			<schema-type>String</schema-type>
			<schema-type>String</schema-type>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<leaf-element-type>String</leaf-element-type>
		</xml-field>
		<class-name>String</class-name>
	</field-to-class-association>
</xml-choice-object-mapping>

XML Choice Collection Mapping

<xml-choice-collection-mapping 
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<container-policy>
		<collection-type>String</collection-type>
	</container-policy>
	<field-to-class-association>
		<xml-field name="String">
			<position>0</position>
			<typed-text-field>1</typed-text-field>
			<single-node>1</single-node>
			<schema-type>String</schema-type>
			<schema-type>String</schema-type>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<leaf-element-type>String</leaf-element-type>
		</xml-field>
		<class-name>String</class-name>
	</field-to-class-association>
	<field-to-class-association>
		<xml-field name="String">
			<position>0</position>
			<typed-text-field>1</typed-text-field>
			<single-node>1</single-node>
			<schema-type>String</schema-type>
			<schema-type>String</schema-type>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<xml-to-java-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</xml-to-java-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<java-to-xml-conversion-pair>
				<qname>String</qname>
				<class-name>String</class-name>
			</java-to-xml-conversion-pair>
			<leaf-element-type>String</leaf-element-type>
		</xml-field>
		<class-name>String</class-name>
	</field-to-class-association>
</xml-choice-collection-mapping>

XML Transformation Mapping

<xml-transformation-mapping xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<attribute-method>String</attribute-method>
	<attribute-transformer>String</attribute-transformer>
	<mutable>true</mutable>
	<indirection/>
	<field-transformations>
		<field-transformation>
			<field name="String"/>
		</field-transformation>
		<field-transformation>
			<field name="String"/>
		</field-transformation>
	</field-transformations>
</xml-transformation-mapping>

XML Any Attribute Mapping

<xml-any-attribute-mapping xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
	<attribute-name>String</attribute-name>
	<read-only>false</read-only>
	<get-method>String</get-method>
	<set-method>String</set-method>
	<properties>
		<property name="String">
			<value>Text</value>
		</property>
		<property name="String">
			<value>Text</value>
		</property>
	</properties>
	<field name="String"/>
	<container>
		<collection-type>String</collection-type>
	</container>
	<include-namespace-declaration>1</include-namespace-declaration>
	<include-schema-instance>1</include-schema-instance>
</xml-any-attribute-mapping>

Design / Functionality

Boot Strapping

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

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.

Back to the top