* 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.

+

*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.

== Concepts ==

== Concepts ==

Line 174:

Line 173:

| align="center" |

| align="center" |

| align="center" | X

| align="center" | X

−

| align="center" |

−

|-

−

| XmlBidirectional (MOXy)

−

| xml-bidirectional

−

| align="center" | X

−

| align="center" |

−

| align="center" |

−

| align="center" |

| align="center" |

| align="center" |

|-

|-

Line 336:

Line 327:

| align="center" |

| align="center" |

|}

|}

−

==== Schema file ====

==== Schema file ====

−

The XML schema that will be supported in EclipseLink 2.0 follows:

+

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].

The externalized metadata file (one per package) can be passed in through a property when creating the JAXBContext.

+

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>

+

** 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 <code>package-name</code> attribute on <code>xml-bindings</code> 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 <code>package-name</code> attribute on <code>xml-bindings</code> element in the bindings file.

Project overview

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 / 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).

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.

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.