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"

(→‎Null Policy)
(→‎Specifying the Externalized Metadata File)
 
(100 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div>
+
<div style="border: 1px solid rgb(0, 0, 0); margin: 5px; padding: 5px; float: right;">__TOC__</div>  
−
= Design Specification: OXM XSD =
+
= Design Specification: OXM XSD =
  
−
[http://bugs.eclipse.org/277920 ER 277920]
+
[http://bugs.eclipse.org/277920 ER 277920]  
 +
 
 +
== Document History  ==
  
−
== Document History ==
 
 
{|{{BMTableStyle}}
 
{|{{BMTableStyle}}
 
|-{{BMTHStyle}}
 
|-{{BMTHStyle}}
−
! Date
+
! Date  
−
! Author
+
! Author  
−
! Version Description & Notes
+
! Version Description &amp; Notes
−
|-  
+
|-
−
| 2009/05/26
+
| 2009/05/26  
−
| Blaise Doughan
+
| Blaise Doughan  
 
| Skeleton
 
| 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 [https://bugs.eclipse.org/bugs/show_bug.cgi?id=293925 ER 293925]
 
|}
 
|}
  
−
== Project overview ==
+
== Project overview ==
  
−
Overview of the project/feature.  Why is it desired, what are its goals.
+
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.
  
−
Goals:
+
Note:
−
* goal 1
+
*This work will continue past the 2.0 release, [https://bugs.eclipse.org/bugs/show_bug.cgi?id=293925 ER 293925] will cover the work extending past the 2.0 release.
−
* goal 2
+
  
−
== Concepts ==
+
== Concepts ==
  
−
Present any concepts relevant to the feature.
+
* 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 ==
  
−
The following sections will expand the goals of this project into more concrete requirements.
+
The following sections will expand the goals of this project into more concrete requirements.  
  
−
== Design Constraints ==
+
== Design Constraints ==
  
−
=== JAXB Annotations ===
+
=== JAXB Annotations ===
  
−
The XML should have the same feel as the JAXB annotations.
+
The XML should have the same feel as the JAXB annotations.  
  
−
[http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/package-summary.html javax.xml.bind.annotation Javadoc]
+
[http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/package-summary.html javax.xml.bind.annotation Javadoc]  
  
−
=== EclipseLink JPA Metadata ===
+
=== EclipseLink JPA Metadata ===
  
−
The XML should have the same feel as the equivalent XML for EclipseLink JPA
+
The XML should have the same feel as the equivalent XML for EclipseLink JPA  
  
−
[http://wiki.eclipse.org/EclipseLink/Development/1.0/ER-200040_DS_M4 EclipseLink JPA XSD]
+
[http://wiki.eclipse.org/EclipseLink/Development/1.0/ER-200040_DS_M4 EclipseLink JPA XSD]  
  
−
=== EclipseLink MOXy Metadata ===
+
=== EclipseLink MOXy Metadata ===
  
−
At a minimum the metadata available in EclipseLink 1.1 must be available in the new format (see below).
+
The metadata that will be available in EclipseLink 2.0 is outlined below.  
  
−
==== XML Direct Mapping ====
+
== Design Phases  ==
−
<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 ====
+
=== JAXB 2.1 annotation support via XML external metadata  ===
  
−
<source lang="xml">
+
This support will be added as outlined in the following phases:  
−
<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>
+
−
</source>
+
  
−
==== XML Composite Object Mapping ====
+
*[http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase1 Phase #1 – Bootstrapping]
 +
**Use EclipseLink external metadata file to provide list of classes
 +
**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. The the following MOXy mappings will be utilized:
 +
***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. The the following MOXy mappings will be utilized:
 +
***Any
 +
***Any Collection
 +
***Any Attribute
 +
*[http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase5 Phase #5 – Reference Mappings]
 +
**Provide support for key based mappings. The the following MOXy mappings will be utilized:
 +
***Object Reference
 +
***Collection Reference
 +
*[http://wiki.eclipse.org/EclipseLink/DesignDocs/277920/Phase5.1 Phase #5.1 – Attachments]
 +
**Provide support for WebService attachments
  
−
<source lang="xml">
+
== Design / Functionality  ==
−
<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 ====
+
=== XML Schema  ===
  
−
<source lang="xml">
+
==== Design Notes ====
−
<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 ====
+
*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 <code>XmlJavaTypeAdapter</code> would correspond to <code>xml-java-type-adapter</code> in XML.
 +
*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.
 +
*To facilitate metadata processing, more specifically to align with MOXy mapping creation, where possible any single valued information (boolean, String, etc.) will be mapped as an attribute in the schema.  Other items with multiple values will be mapped as sub-elements.
  
−
<source lang="xml">
+
==== Annotations to XML  ====
−
<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 ====
+
The following table outlines how annotations relate to schema components:
  
−
<source lang="xml">
+
{|{{BMTableStyle}}
−
<xml-collection-reference-mapping
+
|-{{BMTHStyle}}
−
xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
+
! Annotation
−
<attribute-name>String</attribute-name>
+
! XML
−
<read-only>false</read-only>
+
! Global Element
−
<get-method>String</get-method>
+
! Global Attribute
−
<set-method>String</set-method>
+
! Local Element
−
<properties>
+
! Local Attribute
−
<property name="String">
+
! Enum
−
<value>Text</value>
+
|-
−
</property>
+
| XmlAccessOrder
−
<property name="String">
+
| xml-access-order
−
<value>Text</value>
+
| align="center" |
−
</property>
+
| align="center" |
−
</properties>
+
| align="center" |
−
<reference-class>String</reference-class>
+
| align="center" |
−
<allow-null>true</allow-null>
+
| align="center" | X
−
<field-translations>
+
|-
−
<field-translation>
+
| XmlAccessorOrder
−
<source-field name="String"/>
+
| xml-accessor-order
−
<target-field name="String"/>
+
| align="center" |
−
</field-translation>
+
| align="center" |
−
<field-translation>
+
| align="center" |
−
<source-field name="String"/>
+
| align="center" | X
−
<target-field name="String"/>
+
| align="center" |
−
</field-translation>
+
|-
−
</field-translations>
+
| XmlAccessorType
−
<source-to-target-key-field-association>
+
| xml-accessor-type
−
<field-reference>
+
| align="center" |
−
<source-field name="String"/>
+
| align="center" |
−
<target-field name="String"/>
+
| align="center" |
−
</field-reference>
+
| align="center" | X
−
<field-reference>
+
| align="center" |
−
<source-field name="String"/>
+
|-
−
<target-field name="String"/>
+
| XmlAccessType
−
</field-reference>
+
| xml-access-type
−
</source-to-target-key-field-association>
+
| align="center" |
−
<source-to-target-key-fields>
+
| align="center" |
−
<field name="String"/>
+
| align="center" |
−
<field name="String"/>
+
| align="center" |
−
</source-to-target-key-fields>
+
| align="center" | X
−
<containerpolicy>
+
|-
−
<collection-type>String</collection-type>
+
| XmlAnyAttribute
−
</containerpolicy>
+
| xml-any-attribute
−
<uses-single-node>1</uses-single-node>
+
| align="center" | X
−
</xml-collection-reference-mapping>
+
| align="center" |
−
</source>
+
| 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" |
 +
|-
 +
| XmlElementWrapper
 +
| xml-element-wrapper
 +
| 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" |
 +
|-
 +
| 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
 +
|-
 +
| 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" |
 +
|-
 +
| 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" |
 +
|}
  
−
==== XML Binary Data Mapping ====
+
==== Schema file  ====
  
−
<source lang="xml">
+
The schema file for EclipseLink 2.0 can be found in the <code>eclipselink.jar</code> here: <code>xsd\eclipselink_oxm_2_0.xsd</code>.  The JAR can be downloaded on the [http://www.eclipse.org/eclipselink/downloads/nightly.php EclipseLink nightly build page].
−
<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 ====
+
==== XML Bindings  ====
  
−
==== XML Any Object Mapping ====
+
A given XML metadata bindings file will correspond to a single package. This association is made by using the package name for the key in the properties map that is passed in to the JAXBContext. See [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920#Boot_Strapping below] for information on boot strapping the JAXBContext. The bindings file may contain information that applies to the entire package, as well as class-specific information. The <code>java-type</code> element is used for a java class. Each <code>java-type</code> may have a number of attributes and elements set (refer to the [http://wiki.eclipse.org/EclipseLink/DesignDocs/277920#Schema_file XML Schema] above for more information) as well as zero or more <code>java-attributes</code>. A <code>java-attribute</code> corresponds to a property (field/method). In order to handle various settings applicable to a given property, a number of <code>java-attribute</code> extensions exist:
  
−
<source lang="xml">
+
*xml-java-type-adapter
−
<xml-any-object-mapping
+
*xml-transient
−
xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
+
*xml-any-attribute
−
<attribute-name>String</attribute-name>
+
*xml-attribute
−
<read-only>false</read-only>
+
*xml-any-element
−
<get-method>String</get-method>
+
*xml-element  
−
<set-method>String</set-method>
+
*xml-value
−
<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 ====
+
===== Example  =====
  
−
<source lang="xml">
+
Following is a simple example showing <code>java-attribute</code> use in a bindings file. Here, the 'id' property is set as an attribute and made required, the 'name' property is renamed 'employee-name', and the 'thing' property is set transient. Note that the 'java-attribute' attribute in each corresponds to the field name or method name (for methods, is/set/get is stripped off and the first letter is lower cased).
−
<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 ====
+
====== org.example.Employee.java  ======
  
−
<source lang="xml">
+
<source lang="java">
−
<xml-fragment-mapping
+
package org.example;
−
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 ====
+
public class Employee {
 +
    public int id;
 +
    public String name;
 +
    private Object theThing;
  
−
<source lang="xml">
+
    public void setThing(Object theThing) {
−
<xml-fragment-collection-mapping
+
        this.theThing = theThing;
−
xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
+
    }
−
<attribute-name>String</attribute-name>
+
    public Object getThing() {
−
<read-only>false</read-only>
+
        return theThing;
−
<get-method>String</get-method>
+
    }
−
<set-method>String</set-method>
+
}
−
<properties>
+
</source>  
−
<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 ====
+
====== eclipselink-oxm.xml  ======
  
 
<source lang="xml">
 
<source lang="xml">
−
<xml-choice-object-mapping
+
<?xml version="1.0" encoding="US-ASCII"?>
−
xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
+
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
−
<attribute-name>String</attribute-name>
+
  <java-types>
−
<read-only>false</read-only>
+
    <java-type name="org.example.Employee">
−
<get-method>String</get-method>
+
      <java-attributes>
−
<set-method>String</set-method>
+
        <xml-attribute java-attribute="id" required="true" />
−
<properties>
+
        <xml-element java-attribute="name" name="employee-name" />
−
<property name="String">
+
        <xml-transient java-attribute="thing" />
−
<value>Text</value>
+
      </java-attributes>
−
</property>
+
    </java-type>
−
<property name="String">
+
  </java-types>
−
<value>Text</value>
+
</xml-bindings>
−
</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>
 
</source>
  
−
==== XML Choice Collection Mapping ====
+
=== Boot Strapping  ===
  
−
<source lang="xml">
+
==== Specifying the Externalized Metadata File  ====
−
<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 ====
+
The externalized metadata file (one per package) can be passed in through a property when creating the JAXBContext. Prior to EclipseLink 2.2 the only supported input format for specifying the externalized metadata file(s) was <code>Map<String, Source></code>.  For EclipseLink 2.2, however, the following will be supported:
−
 
+
* Map<String, Object>
−
<source lang="xml">
+
** String is the package name
−
<xml-transformation-mapping xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
+
** Object is one of File, Reader, etc. listed below
−
<attribute-name>String</attribute-name>
+
* List<Object>
−
<read-only>false</read-only>
+
** Object is one of File, Reader, etc. listed below
−
<get-method>String</get-method>
+
** Package name is set via <code>package-name</code> attribute on <code>xml-bindings</code> element in the bindings file.
−
<set-method>String</set-method>
+
* One of:
−
<properties>
+
** java.io.File
−
<property name="String">
+
** java.io.InputStream
−
<value>Text</value>
+
** java.io.Reader
−
</property>
+
** java.net.URL
−
<property name="String">
+
** javax.xml.stream.XMLEventReader
−
<value>Text</value>
+
** javax.xml.stream.XMLStreamReader
−
</property>
+
** javax.xml.transform.Source
−
</properties>
+
** org.w3c.dom.Node
−
<attribute-method>String</attribute-method>
+
** org.xml.sax.InputSource
−
<attribute-transformer>String</attribute-transformer>
+
** --
−
<mutable>true</mutable>
+
** Package name is set via <code>package-name</code> attribute on <code>xml-bindings</code> element in the bindings file.
−
<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 ===
+
−
 
+
−
==== Default Behaviour ====
+
−
 
+
−
When creating a JAXBContext an eclipselink-oxm.xml file will be looked for, for each item on the context path.
+
  
 +
==== Example:  Map<String, Object> ====
 
<source lang="java">
 
<source lang="java">
−
JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader);
+
InputStream employeeExternalizedMetadata =
−
</source>
+
    aClassLoader.getResourceAsStream("org/example/employee/metadata.xml";
 +
InputStream customerExternalizedMetadata =
 +
    aClassLoader.getResourceAsStream("org/example/customer/metadata.xml";
  
−
The ClassLoader parameter will be used to find the eclipselink-oxm.xml file in a manner similar to:
+
HashMap<String, Source> metadataSourceMap = new HashMap<String, Source>();
 +
metadataSourceMap.put("org.example.employee", new StreamSource(employeeExternalizedMetadata));
 +
metadataSourceMap.put("org.example.customer", new StreamSource(customerExternalizedMetadata));
  
−
<source lang="java">
+
Map<String, Map<String, Source>> properties = new HashMap<String, Map<String, Source>>();
−
InputStream externalizedMetadata1 =
+
properties.put("eclipselink-oxm-xml", metadataSourceMap);
−
    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);
 
JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader, properties);
−
</source>
+
</source>  
  
−
Use of the property is the only means of using the externalized metadata when creating the JAXBContext based on an array of classes.
+
Following is an example of how to pass in the property when creating the JAXBContext based on an array of classes:
  
 
<source lang="java">
 
<source lang="java">
−
Class[] classes = new Class[3];
+
Class[] classes = new Class[2];
 
classes[0] = Customer.class;
 
classes[0] = Customer.class;
 
classes[1] = Employee.class;
 
classes[1] = Employee.class;
−
classes[2] = Address.class;
 
 
JAXBContext.newInstance(classes, properties);
 
JAXBContext.newInstance(classes, properties);
 
</source>
 
</source>
  
−
=== Common Mapping Metadata ===
+
==== Example:  List<Object> ====
 +
<source lang="java">
 +
List<Object> inputFiles = new ArrayList<Object>();
 +
inputFiles.add(new java.io.File("org/example/employee/metadata.xml"));
 +
inputFiles.add(new java.io.FileInputStream("org/example/customer/metadata.xml"));
  
−
==== XML Schema ====
+
Map<String, Object> properties = new HashMap<String, Object>();
 +
properties.put("eclipselink-oxm-xml", inputFiles);
  
−
<source lang="xml">
+
Class[] classes = new Class[] { org.example.employee.Employee.class, org.example.customer.Customer.class };
−
<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">
+
JAXBContext.newInstance(classes, 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>
 
</source>
  
−
==== XML ====
+
Following shows sample externalized metadata files for Employee and Customer:
−
 
+
===== org/example/employee/metadata.xml =====
 
<source lang="xml">
 
<source lang="xml">
−
<xml-mapping
+
<?xml version="1.0" encoding="US-ASCII"?>
−
attribute-name="String"  
+
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" package-name="org.example.employee">
−
read-only="false"  
+
    <java-types>
−
get-method="String"  
+
        <java-type name="Employee">
−
set-method="String">
+
            <xml-root-element name="emp"/>
−
<properties>
+
            <java-attributes>
−
<property name="String" value="String"/>
+
                <xml-attribute java-attribute="id"/>
−
<property name="String" value="String"/>
+
            </java-attributes>
−
</properties>
+
        </java-type>
−
</xml-mapping>
+
    </java-types>
 +
</xml-bindings>
 
</source>
 
</source>
−
 
+
===== org/example/customer/metadata.xml =====
−
 
+
−
=== Null Policy ===
+
−
 
+
−
==== XML Schema ====
+
−
 
+
 
<source lang="xml">
 
<source lang="xml">
−
<xs:element name="null-policy">
+
<?xml version="1.0" encoding="US-ASCII"?>
−
    <xs:complexType>
+
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" package-name="org.example.customer">
−
        <xs:attribute name="set-performed-for-absent-node" type="xs:boolean" default="true"/>
+
    <java-types>
−
        <xs:attribute name="null-represented-by-empty-node" type="xs:boolean" default="false"/>
+
         <java-type name="Customer">
−
        <xs:attribute name="null-represented-by-xsi-nil" type="xs:boolean" default="false"/>
+
             <xml-root-element name="cust"/>
−
         <xs:attribute name="marshal-null-representation">
+
            <java-attributes>
−
             <xs:simpleType>
+
                <xml-attribute java-attribute="id"/>
−
                <xs:restriction base="xs:string">
+
             </java-attributes>
−
                    <xs:enumeration value="XSI_NIL"/>
+
         </java-type>
−
                    <xs:enumeration value="ABSENT_NODE"/>
+
     </java-types>
−
                    <xs:enumeration value="EMPTY_NODE"/>
+
</xml-bindings>
−
                </xs:restriction>
+
−
             </xs:simpleType>
+
−
         </xs:attribute>
+
−
     </xs:complexType>
+
−
</xs:element>
+
 
</source>
 
</source>
  
−
==== XML ====
+
==== Example:  java.io.File ====
−
 
+
 
<source lang="java">
 
<source lang="java">
−
<null-policy>
+
Map<String, Object> properties = new HashMap<String, Object>();
−
    <xsi-nil-represents-null>false</xsi-nil-represents-null>
+
properties.put("eclipselink-oxm-xml", new java.io.File("org/example/customer/metadata.xml")));
−
    <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 ===
+
Class[] classes = new Class[] { org.example.customer.Customer.class };
  
−
==== Annotations ====
+
JAXBContext.newInstance(classes, properties);
−
 
+
−
<source lang="java">
+
−
@XmlAnyAttribute
+
−
@IncludeNamespaceDeclaration(value=true)
+
−
@IncludeSchemaInstance(value=true)
+
 
</source>
 
</source>
  
−
==== XML Schema ====
+
Following shows a sample externalized metadata file for Customer:
−
 
+
===== org/example/customer/metadata.xml =====
 
<source lang="xml">
 
<source lang="xml">
−
<xs:element name="xml-any-attribute-mapping">
+
<?xml version="1.0" encoding="US-ASCII"?>
−
<xs:complexType>
+
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" package-name="org.example.customer">
−
<xs:complexContent>
+
    <java-types>
−
<xs:extension base="xml-mapping">
+
        <java-type name="Customer">
−
<xs:attribute name="include-namespace-declaration" type="xs:boolean"/>
+
            <xml-root-element name="cust"/>
−
<xs:attribute name="include-schema-instance" type="xs:boolean"/>
+
            <java-attributes>
−
</xs:extension>
+
                <xml-attribute java-attribute="id"/>
−
</xs:complexContent>
+
            </java-attributes>
−
</xs:complexType>
+
        </java-type>
−
</xs:element>
+
    </java-types>
 +
</xml-bindings>
 
</source>
 
</source>
  
−
==== XML ====
+
== Testing  ==
  
−
<source lang="xml">
+
== API  ==
−
<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 ===
+
== GUI  ==
  
−
<source lang="xml">
+
== Config files  ==
−
<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: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>
+
  
−
== Testing ==
+
== Documentation  ==
  
−
== API ==
+
== Open Issues  ==
  
−
== GUI ==
+
This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.  
−
 
+
−
== 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.
+
  
 
{|{{BMTableStyle}}
 
{|{{BMTableStyle}}
 
|-{{BMTHStyle}}
 
|-{{BMTHStyle}}
−
! Issue #
+
! Issue #  
−
! Owner
+
! Owner  
 
! Description / Notes
 
! Description / Notes
−
|-  
+
|-
−
|
+
|  
−
|
+
|  
−
|
+
|  
 
|}
 
|}
  
−
== Decisions ==
+
== 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.
+
This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.  
  
 
{|{{BMTableStyle}}
 
{|{{BMTableStyle}}
 
|-{{BMTHStyle}}
 
|-{{BMTHStyle}}
−
! Issue #
+
! Issue #  
−
! Description / Notes
+
! Description / Notes  
 
! Decision
 
! Decision
−
|-  
+
|-
−
|
+
|  
−
|
+
|  
−
|
+
|  
 
|}
 
|}
  
−
== Future Considerations ==
+
== 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.
 
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.

Latest revision as of 12:38, 25 November 2010

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 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 will continue past the 2.0 release, ER 293925 will cover the work extending past the 2.0 release.

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

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

Design Notes

  • 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.
  • 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.
  • To facilitate metadata processing, more specifically to align with MOXy mapping creation, where possible any single valued information (boolean, String, etc.) will be mapped as an attribute in the schema. Other items with multiple values will be mapped as sub-elements.

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
XmlElementWrapper xml-element-wrapper X
XmlID xml-id X
XmlIDREF xml-idref 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
XmlRootElement xml-root-element X
XmlSchema xml-schema 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.0 can be found in the eclipselink.jar here: xsd\eclipselink_oxm_2_0.xsd. The JAR can be downloaded on the EclipseLink nightly build page.

XML Bindings

A given XML metadata bindings file will correspond to a single package. This association is made by using the package name for the key in the properties map that is passed in to the JAXBContext. See below for information on boot strapping the JAXBContext. The bindings file may contain information that applies to the entire package, as well as class-specific information. The java-type element is used for a java class. Each java-type may have a number of attributes and elements set (refer to the XML Schema above for more information) as well as zero or more java-attributes. A java-attribute corresponds to a property (field/method). In order to handle various settings applicable to a given property, a number of java-attribute extensions exist:

  • xml-java-type-adapter
  • xml-transient
  • xml-any-attribute
  • xml-attribute
  • xml-any-element
  • xml-element
  • xml-value
Example

Following is a simple example showing java-attribute use in a bindings file. Here, the 'id' property is set as an attribute and made required, the 'name' property is renamed 'employee-name', and the 'thing' property is set transient. Note that the 'java-attribute' attribute in each corresponds to the field name or method name (for methods, is/set/get is stripped off and the first letter is lower cased).

org.example.Employee.java
package org.example;
 
public class Employee {
    public int id;
    public String name;
    private Object theThing;
 
    public void setThing(Object theThing) {
        this.theThing = theThing;
    }
    public Object getThing() { 
        return theThing;
    }
}
eclipselink-oxm.xml
<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
  <java-types>
    <java-type name="org.example.Employee">
      <java-attributes>
        <xml-attribute java-attribute="id" required="true" />
        <xml-element java-attribute="name" name="employee-name" />
        <xml-transient java-attribute="thing" />
      </java-attributes>
    </java-type>
  </java-types>
</xml-bindings>

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. Prior to EclipseLink 2.2 the only supported input format for specifying the externalized metadata file(s) was Map<String, Source>. For EclipseLink 2.2, however, the following will be supported:

  • Map<String, Object>
    • String is the package name
    • Object is one of File, Reader, etc. listed below
  • List<Object>
    • Object is one of File, Reader, etc. listed below
    • Package name is set via package-name attribute on xml-bindings element in the bindings file.
  • One of:
    • java.io.File
    • java.io.InputStream
    • java.io.Reader
    • java.net.URL
    • javax.xml.stream.XMLEventReader
    • javax.xml.stream.XMLStreamReader
    • javax.xml.transform.Source
    • org.w3c.dom.Node
    • org.xml.sax.InputSource
    • --
    • Package name is set via package-name attribute on xml-bindings element in the bindings file.

Example: Map<String, Object>

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);

Example: List<Object>

List<Object> inputFiles = new ArrayList<Object>();
inputFiles.add(new java.io.File("org/example/employee/metadata.xml"));
inputFiles.add(new java.io.FileInputStream("org/example/customer/metadata.xml"));
 
Map<String, Object> properties = new HashMap<String, Object>();
properties.put("eclipselink-oxm-xml", inputFiles);
 
Class[] classes = new Class[] { org.example.employee.Employee.class, org.example.customer.Customer.class };
 
JAXBContext.newInstance(classes, properties);

Following shows sample externalized metadata files for Employee and Customer:

org/example/employee/metadata.xml
<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" package-name="org.example.employee">
    <java-types>
        <java-type name="Employee">
            <xml-root-element name="emp"/>
            <java-attributes>
                <xml-attribute java-attribute="id"/>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>
org/example/customer/metadata.xml
<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" package-name="org.example.customer">
    <java-types>
        <java-type name="Customer">
            <xml-root-element name="cust"/>
            <java-attributes>
                <xml-attribute java-attribute="id"/>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Example: java.io.File

Map<String, Object> properties = new HashMap<String, Object>();
properties.put("eclipselink-oxm-xml", new java.io.File("org/example/customer/metadata.xml")));
 
Class[] classes = new Class[] { org.example.customer.Customer.class };
 
JAXBContext.newInstance(classes, properties);

Following shows a sample externalized metadata file for Customer:

org/example/customer/metadata.xml
<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" package-name="org.example.customer">
    <java-types>
        <java-type name="Customer">
            <xml-root-element name="cust"/>
            <java-attributes>
                <xml-attribute java-attribute="id"/>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

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.

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

This page was last modified 12:38, 25 November 2010 by David McCann. Based on work by Denise Mahar and Blaise Doughan.

Back to the top