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/293925"

(New page: <div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div> = Design Specification: OXM XSD = [http://bugs.eclipse.org/277920 ER 277920] == Document History ==...)
 
(→‎Testing)
 
(39 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div>
 
<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div>
−
= Design Specification: OXM XSD =
+
= Design Specification: MOXy - OXM XSD =
  
−
[http://bugs.eclipse.org/277920 ER 277920]
+
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=293925 ER 293925]
  
 
== Document History ==
 
== Document History ==
Line 10: Line 10:
 
! Author
 
! Author
 
! Version Description & Notes
 
! Version Description & Notes
−
|-
 
−
| 2009/05/26
 
−
| Blaise Doughan
 
−
| Skeleton
 
 
|-  
 
|-  
 
| 2009/11/09
 
| 2009/11/09
 
| David McCann
 
| 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 [https://bugs.eclipse.org/bugs/show_bug.cgi?id=293925 Enhancement# 293925]
+
| Initial Contribution.  The work outlined in this design document is a continuation of the work done for [http://bugs.eclipse.org/277920 ER 277920]
 +
|-
 +
| 2009/12/08
 +
| David McCann
 +
| Bringing page up to date:  xml schema, goals, etc. needed attention.
 
|}
 
|}
  
Line 23: Line 23:
  
 
Goals:
 
Goals:
−
* Support JAXB 2.1 annotations via XML external metadata
+
* Support JAXB 2.1 annotations via XML external metadata.
−
* Add additional support to satisfy WebServices requirements
+
* Support MOXy metadata (used to extend JAXB) via external metadata.
−
* Support OXM mappings via XML external metadata
+
* Support the use of the XML metadata as a means to override metadata specified by annotations.
 +
 
 +
Note:
 +
* This work is a continuation of support added for [https://bugs.eclipse.org/bugs/show_bug.cgi?id=277920 ER 277920]
  
 
== Concepts ==
 
== Concepts ==
  
−
None to mention.
+
*  Although JAXB annotations can be applied independently they are logically linked. For example @XmlList can only be used with XmlElement, XmlAttribute, XmlValue, XmlIDREF. These rules will be enforced through the XML metadata.
 +
* Overriding will be handled at the property level.
  
 
== Requirements ==
 
== Requirements ==
Line 58: Line 62:
  
 
This support will be added as outlined in the following phases:
 
This support will be added as outlined in the following phases:
−
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase1 Phase #1 – Bootstrapping]
+
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/Phase6 Phase #6 – Substitution Groups]
−
** Use eclipselink-oxm.xml file to provide list of classes
+
** Provide support for substitution groups.  The the following MOXy mappings will be utilized:
−
** Allow basic schema to be generated
+
−
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase2 Phase #2 – High Level Metadata]
+
−
** Provide core type metadata
+
−
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase3 Phase #3 – Containment Mappings]
+
−
** Provide support for nested data via the following mappings:
+
−
*** Direct
+
−
*** Direct Collection
+
−
*** Composite Object
+
−
*** Composite Collection
+
−
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase4 Phase #4 – Any/Choice Content]
+
−
** Provide support for wild card data via the following mappings:
+
−
*** Any
+
−
*** Any Collection
+
−
*** Any Attribute
+
−
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase5 Phase #5 – Reference Mappings]
+
−
** Provide support for key based mappings via the following mappings:
+
−
*** Object Reference
+
−
*** Collection Reference
+
−
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase6 Phase #6 – Substitution Groups]
+
−
** Provide support for substitution groups via the following mappings:
+
 
*** Choice
 
*** Choice
 
*** Choice Collection
 
*** Choice Collection
−
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase7 Phase #7 – Schema Customization]
+
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/Phase7 Phase #7 – Schema Customization]
 
** Allow customized mapping to an XML Schema built in type
 
** Allow customized mapping to an XML Schema built in type
−
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase8 Phase #8 – Enums]
+
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/Phase8 Phase #8 – Enums]
 
** Provide support for Java Enums
 
** Provide support for Java Enums
−
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase9 Phase #9 – Attachments]
+
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/Phase9 Phase #9 – Attachments]
 
** Provide support for WebService attachments
 
** Provide support for WebService attachments
−
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase10 Phase #10 – XML Registry]
+
* [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/Phase10 Phase #10 – XML Registry]
 
** Provide support for ObjectFactory methods
 
** Provide support for ObjectFactory methods
  
−
==== XML Direct Mapping ====
+
=== XML external metadata support for WebServices ===
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
  
−
==== XML Composite Direct Collection Mapping ====
+
TBD.
  
−
<source lang="xml">
+
=== OXM mapping support via XML external metadata ===
−
<xml-composite-direct-collection-mapping  
+
Design for this portion of the project can be found [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/MOXyExtensions here].
−
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>
+
−
</source>
+
  
−
==== XML Composite Object Mapping ====
+
== Design / Functionality ==
  
−
<source lang="xml">
+
=== XML Schema  ===
−
<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>
+
−
</source>
+
  
−
==== XML Composite Collection Mapping ====
+
==== Design Notes ====
  
−
<source lang="xml">
+
===== [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920#Design_Notes Design notes from 2.0 release] =====
−
<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>
+
−
</source>
+
  
−
==== XML Object Reference Mapping ====
+
==== Annotations to XML ====
  
−
<source lang="xml">
+
The following table outlines how annotations relate to schema components:  
−
<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>
+
−
</source>
+
  
−
==== XML Collection Reference Mapping ====
+
{|{{BMTableStyle}}
 +
|-{{BMTHStyle}}
 +
! Annotation
 +
! XML
 +
! Global Element
 +
! Global Attribute
 +
! Local Element
 +
! Local Attribute
 +
! Enum
 +
|-
 +
| XmlAccessOrder
 +
| xml-access-order
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
|-
 +
| XmlAccessorOrder
 +
| xml-accessor-order
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
|-
 +
| XmlAccessorType
 +
| xml-accessor-type
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
|-
 +
| XmlAccessType
 +
| xml-access-type
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
|-
 +
| XmlAnyAttribute
 +
| xml-any-attribute
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlAnyElement
 +
| xml-any-element
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlAttribute
 +
| xml-attribute
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlAttributeRef
 +
| xml-attribute-ref
 +
| align="center" | 
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
|-
 +
| XmlCustomizer (MOXy)
 +
| xml-customizer
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
|-
 +
| XmlElement
 +
| xml-element
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlElementDecl
 +
| xml-element-decl
 +
| align="center" | 
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlElements
 +
| xml-elements
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlElementRef
 +
| xml-element-ref
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlElementRefs
 +
| xml-element-refs
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlElementWrapper
 +
| xml-element-wrapper
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlEnum
 +
| xml-enum
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlEnumValue
 +
| xml-enum-value
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlID
 +
| xml-id
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
|-
 +
| XmlIDREF
 +
| xml-idref
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
|-
 +
| XmlInlineBinaryData
 +
| xml-inline-binary-data
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
|-
 +
| XmlJavaTypeAdapter
 +
| xml-java-type-adapter
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlJavaTypeAdapters
 +
| xml-java-type-adapters
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlList
 +
| xml-List
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
|-
 +
| N/A
 +
| xml-map
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | 
 +
| align="center" |
 +
|-
 +
| XmlMimeType
 +
| xml-mime-type
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
|-
 +
| XmlMixed
 +
| xml-mixed
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
|-
 +
| XmlNs
 +
| xml-ns
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlNsForm
 +
| xml-ns-form
 +
| align="center" |
 +
| align="center" |
 +
| align="center" | 
 +
| align="center" |
 +
| align="center" | X
 +
|-
 +
| XmlRegistry
 +
| xml-registry
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlRootElement
 +
| xml-root-element
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlSchema
 +
| xml-schema
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlSchemaType
 +
| xml-schema-type
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlSchemaTypes
 +
| xml-schema-types
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlSeeAlso
 +
| xml-see-also
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlTransient
 +
| xml-transient
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlType
 +
| xml-type
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|-
 +
| XmlValue
 +
| xml-value
 +
| align="center" | X
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
| align="center" |
 +
|}
  
−
<source lang="xml">
+
==== Schema file  ====
−
<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>
+
−
</source>
+
  
−
==== XML Binary Data Mapping ====
+
The schema file for EclipseLink 2.1 can be found in the <code>eclipselink.jar</code> here: <code>xsd\eclipselink_oxm_2_1.xsd</code>.  The JAR can be downloaded on the [http://www.eclipse.org/eclipselink/downloads/nightly.php EclipseLink nightly build page].
  
−
<source lang="xml">
+
==== XML Bindings  ====
−
<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>
+
−
</source>
+
  
−
==== XML Binary Data Collection Mapping ====
+
==== [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920#XML_Bindings Bindings info/example from 2.0] ====
−
 
+
−
==== XML Any Object Mapping ====
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
==== XML Any Collection Mapping ====
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
==== XML Fragment Mapping ====
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
==== XML Fragment Collection ====
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
==== XML Choice Object Mapping ====
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
==== XML Choice Collection Mapping ====
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
==== XML Transformation Mapping ====
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
==== XML Any Attribute Mapping ====
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
== Design / Functionality ==
+
  
 
=== Boot Strapping ===
 
=== Boot Strapping ===
  
−
==== Default Behaviour ====
+
==== [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920#Boot_Strapping Specifying the Externalized Metadata File] ====
−
 
+
−
When creating a JAXBContext an eclipselink-oxm.xml file will be looked for, for each item on the context path.
+
−
 
+
−
<source lang="java">
+
−
JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader);
+
−
</source>
+
−
 
+
−
The ClassLoader parameter will be used to find the eclipselink-oxm.xml file in a manner similar to:
+
−
 
+
−
<source lang="java">
+
−
InputStream externalizedMetadata1 =
+
−
    aClassLoader.getResourceAsStream("org/example/customer/eclipselink-oxm.xml";
+
−
InputStream externalizedMetadata2 =
+
−
    aClassLoader.getResourceAsStream("org/example/employee/eclipselink-oxm.xml";
+
−
</source>
+
−
 
+
−
==== Specifying the Externalized Metadata File ====
+
−
 
+
−
If you want to override the name and location of the externalized metadata this can be done through a property when creating the JAXBContext.
+
−
 
+
−
<source lang="java">
+
−
Map<String, Object> properties = new HashMap<String, Object>();
+
−
properties.put("eclipselink.oxm.metadata",
+
−
    "org/example/employee/metadata.xml:org/example/customer/metadata.xml");
+
−
</source>
+
−
 
+
−
If the property is specified then no eclipselink-oxm.xml files will be looked for, only the specified files will be used.
+
−
 
+
−
<source lang="java">
+
−
JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader, properties);
+
−
</source>
+
−
 
+
−
Use of the property is the only means of using the externalized metadata when creating the JAXBContext based on an array of classes.
+
−
 
+
−
<source lang="java">
+
−
Class[] classes = new Class[3];
+
−
classes[0] = Customer.class;
+
−
classes[1] = Employee.class;
+
−
classes[2] = Address.class;
+
−
JAXBContext.newInstance(classes, properties);
+
−
</source>
+
−
 
+
−
=== Common Mapping Metadata ===
+
−
 
+
−
==== XML Schema ====
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
==== XML ====
+
−
 
+
−
<source lang="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>
+
−
</source>
+
−
 
+
−
 
+
−
=== Null Policy ===
+
−
 
+
−
==== XML Schema ====
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
==== XML ====
+
−
 
+
−
<source lang="java">
+
−
<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>
+
−
</source>
+
−
 
+
−
=== XML Any Attribute Mapping ===
+
−
 
+
−
==== Annotations ====
+
−
 
+
−
<source lang="java">
+
−
@XmlAnyAttribute
+
−
@IncludeNamespaceDeclaration(value=true)
+
−
@IncludeSchemaInstance(value=true)
+
−
</source>
+
−
 
+
−
==== XML Schema ====
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
==== XML ====
+
−
 
+
−
<source lang="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>
+
−
</source>
+
−
 
+
−
=== XML Attribute ===
+
−
 
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
−
 
+
−
=== XML Element ===
+
−
<source lang="xml">
+
−
<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>
+
−
</source>
+
  
 
== Testing ==
 
== Testing ==
 +
The basic testing strategy will be to have a test suite for each annotation (JAXB) and mapping (MOXy).  Each suite will, at a minimum, test schema generation, unmarshal and marshal operations.
  
 
== API ==
 
== API ==

Latest revision as of 11:09, 26 February 2010

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
2009/12/08 David McCann Bringing page up to date: xml schema, goals, etc. needed attention.

Project overview

Goals:

  • Support JAXB 2.1 annotations via XML external metadata.
  • Support MOXy metadata (used to extend JAXB) via external metadata.
  • Support the use of the XML metadata as a means to override metadata specified by annotations.

Note:

  • This work is a continuation of support added for ER 277920

Concepts

  • Although JAXB annotations can be applied independently they are logically linked. For example @XmlList can only be used with XmlElement, XmlAttribute, XmlValue, XmlIDREF. These rules will be enforced through the XML metadata.
  • Overriding will be handled at the property level.

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

JAXB 2.1 annotation support via XML external metadata

This support will be added as outlined in the following phases:

XML external metadata support for WebServices

TBD.

OXM mapping support via XML external metadata

Design for this portion of the project can be found here.

Design / Functionality

XML Schema

Design Notes

Design notes from 2.0 release

Annotations to XML

The following table outlines how annotations relate to schema components:

Annotation XML Global Element Global Attribute Local Element Local Attribute Enum
XmlAccessOrder xml-access-order X
XmlAccessorOrder xml-accessor-order X
XmlAccessorType xml-accessor-type X
XmlAccessType xml-access-type X
XmlAnyAttribute xml-any-attribute X
XmlAnyElement xml-any-element X
XmlAttribute xml-attribute X
XmlAttributeRef xml-attribute-ref X
XmlCustomizer (MOXy) xml-customizer X
XmlElement xml-element X
XmlElementDecl xml-element-decl X
XmlElements xml-elements X
XmlElementRef xml-element-ref X
XmlElementRefs xml-element-refs X
XmlElementWrapper xml-element-wrapper X
XmlEnum xml-enum X
XmlEnumValue xml-enum-value X
XmlID xml-id X
XmlIDREF xml-idref X
XmlInlineBinaryData xml-inline-binary-data X
XmlJavaTypeAdapter xml-java-type-adapter X
XmlJavaTypeAdapters xml-java-type-adapters X
XmlList xml-List X
N/A xml-map X
XmlMimeType xml-mime-type X
XmlMixed xml-mixed X
XmlNs xml-ns X
XmlNsForm xml-ns-form X
XmlRegistry xml-registry X
XmlRootElement xml-root-element X
XmlSchema xml-schema X
XmlSchemaType xml-schema-type X
XmlSchemaTypes xml-schema-types X
XmlSeeAlso xml-see-also X
XmlTransient xml-transient X
XmlType xml-type X
XmlValue xml-value X

Schema file

The schema file for EclipseLink 2.1 can be found in the eclipselink.jar here: xsd\eclipselink_oxm_2_1.xsd. The JAR can be downloaded on the EclipseLink nightly build page.

XML Bindings

Bindings info/example from 2.0

Boot Strapping

Specifying the Externalized Metadata File

Testing

The basic testing strategy will be to have a test suite for each annotation (JAXB) and mapping (MOXy). Each suite will, at a minimum, test schema generation, unmarshal and marshal operations.

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.

Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/DesignDocs/293925&oldid=190853"

This page was last modified 11:09, 26 February 2010 by David McCann.

Back to the top