EclipseLink/DesignDocs/277920/Phase4

Phase 4 (page under construction)

Provide support for high level metadata.

Annotations

The following annotations will be targetted in this phase:

Annotation	Package	Type	Field	Method
XmlElementWrapper			X	X
XmlList			X	X
XmlValue			X	X
XmlAnyElement			X	X

Example: XmlElementWrapper and XmlList annotations

Java Metadata

The following example will demonstrate how the XmlElementWrapper and XmlList annotations can be applied:

org.example.Employee.java

package org.example;
 
import javax.xml.bind.annotation.XmlElementWrapper;
import javax.xml.bind.annotation.XmlList;
 
public class Employee {
    @XmlElementWrapper(name="my-digits", namespace="urn:employee", nillable=true, required=true)
    public int[] digits;
 
    @XmlList
    public java.util.List<String> data;
}

XML Metadata

xml-element-wrapper

If this is present in the XML then it completely replaces the corresponding annotation.

xml-list

If this is present in the XML then the true/false value set via the corresponding annotation is ignored.

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" class.

<?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-element java-attribute="digits">
                <xml-element-wrapper name="my-digits" namespace="urn:employee" nillable="true" required="true" />
            </xml-element>
            <xml-element java-attribute="data" xml-list="true" />
        </java-attributes>
    </java-type>
  </java-types>
</xml-bindings>

Example: XmlValue annotation

Java Metadata

The following example will demonstrate how the XmlValue annotation can be applied:

org.example.Employee.java

package org.example;
 
import javax.xml.bind.annotation.XmlValue;
 
public class Employee {
    @XmlValue
    public java.math.BigDecimal salary;
}

XML Metadata

xml-value

An @XmlValue annotation cannot be un-set via XML. Hence, any/all @XmlValue annotations will be processed in addition to any/all xml-value entries in XML (for a given class). Note that only one field/property can be set as @XmlValue or xml-value on a given class.

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" class.

<?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-value java-attribute="salary" />
        </java-attributes>
    </java-type>
  </java-types>
</xml-bindings>