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, all @XmlValue annotations will be processed in addition to 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>

Example: XmlAnyElement annotation

Java Metadata

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

org.example.Employee.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Employee {
    public int a;
    public String b;
 
    @javax.xml.bind.annotation.XmlAnyElement(lax=true, value=org.example.MyDomHandler.class)
    public java.util.List<Object> stuff;
}

org.example.MyDomHandler.java

package org.example;
 
import javax.xml.bind.ValidationEventHandler;
import javax.xml.bind.annotation.DomHandler;
import javax.xml.bind.annotation.W3CDomHandler;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
import javax.xml.transform.dom.DOMResult;
 
import org.w3c.dom.Element;
 
/**
 * This handler simply wraps a W3CDomHandler.
 */
public class MyDomHandler implements DomHandler {
    W3CDomHandler theHandler;
 
    public MyDomHandler() {
        theHandler = new W3CDomHandler();
    }
 
    public Result createUnmarshaller(ValidationEventHandler errorHandler) {
        return theHandler.createUnmarshaller(errorHandler);
    }
 
    public Object getElement(Result rt) {
        if (rt instanceof DOMResult) {
            return theHandler.getElement((DOMResult) rt);
        }
        return null;
    }
 
    public Source marshal(Object n, ValidationEventHandler errorHandler) {
        if (n instanceof Element) {
            return theHandler.marshal((Element) n, errorHandler);
        }
        return null;
    }
}

XML Metadata

xml-any-element

If this is present in the XML then it completely replaces the corresponding annotation. An @XmlAnyElement annotation cannot be un-set via XML. Hence, all @XmlAnyElement annotations will be processed in addition to all xml-any-element entries in XML (for a given class). Note that only one field/property can be set as @XmlAnyElement or xml-any-element 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-any-element java-attribute="stuff" lax="true" dom-handler="org.example.MyDomHandler"/>
      </java-attributes>
    </java-type>
  </java-types>
</xml-bindings>