EclipseLink/DesignDocs/277920/Phase4

Phase 4 - Any/Choice Content

Provide support for wild card data.

Annotations

The following annotations will be targetted in this phase:

Annotation	XML Metadata Tag	Package	Type	Field	Method
XmlElementWrapper	xml-element-wrapper			X	X
XmlList	xml-list			X	X
XmlValue	xml-value			X	X
XmlAnyElement	xml-any-element			X	X
XmlAnyAttribute	xml-any-attribute			X	X
XmlMixed	xml-mixed			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 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

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.

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>

xml-any-element with xml-element-ref(s)

xml-any-element can be used with xml-element-ref(s) by nesting the xml-element-refs declaration within the xml-any-element structure. For example:

<?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">
         <xml-root-element name="emp" />
         <java-attributes>
            <xml-any-element java-attribute="stuff">
               <xml-element-refs>
                  <xml-element-ref name="a" type="java.lang.String" />
                  <xml-element-ref name="b" type="java.lang.Integer" />
               </xml-element-refs>
            </xml-any-element>
         </java-attributes>
      </java-type>
   </java-types>
</xml-bindings>

It is assumed here that java-attribute will be set on the enclosing xml-any-element. If java-attribute is set on the enclosed xml-element-refs it will not be processed.

Proposed XSD changes

An xml-element-refs element ref will be added to xml-any-element. We will not support xml-element-ref on its own - in the case where a single xml-element-ref is desired it must be wrapped in an xml-element-refs. This limitation is necessary due to the fact that the element declarations are in an all which does not support choice. Switching the all to a sequence would allow for a choice, and hence the ability to have xml-element-refs OR xml-element-ref, but this could potentially cause errors in existing instance documents as sequence forces ordering of elements.

<xs:element name="xml-any-element" substitutionGroup="java-attribute">
   <xs:complexType>
      <xs:complexContent>
         <xs:extension base="java-attribute">
            <xs:all>
               <xs:element ref="xml-access-methods" minOccurs="0" />
               <xs:element ref="xml-java-type-adapter" minOccurs="0"/>
               <xs:element ref="xml-properties" minOccurs="0" />
               <xs:element ref="xml-element-refs" minOccurs="0" />
            </xs:all>
            <xs:attribute name="xml-mixed" type="xs:boolean" default="false" />
            <xs:attribute name="lax" type="xs:boolean" default="false" />
            <xs:attribute name="dom-handler" type="xs:string" default="javax.xml.bind.annotation.W3CDomHandler" />
            <xs:attribute name="read-only" type="xs:boolean" default="false" />
            <xs:attribute name="write-only" type="xs:boolean" default="false" />
            <xs:attribute name="xml-path" type="xs:string" />
            <xs:attribute name="container-type" type="xs:string" default="##default" />
         </xs:extension>
      </xs:complexContent>
   </xs:complexType>
</xs:element>

Example: XmlAnyAttribute annotation

Java Metadata

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

org.example.Employee.java

package org.example;
 
import javax.xml.namespace.QName;
 
@javax.xml.bind.annotation.XmlRootElement
public class Employee {
    public int a;
    public String b;
 
    @javax.xml.bind.annotation.XmlAnyAttribute
    public java.util.Map<QName, Object> stuff;
}

XML Metadata

xml-any-attribute

If this is present in the XML then the associated property will be treated as an Any property.

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">
            <xml-root-element name="employee" />
            <java-attributes>
                <xml-any-attribute java-attribute="stuff" />
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Example: XmlMixed annotation

Java Metadata

The following example will demonstrate how the XmlMixed 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
    @javax.xml.bind.annotation.XmlMixed
    public java.util.List<Object> stuff;
}

XML Metadata

xml-mixed

If this is present, and set to "true", in the XML then the associated property will be treated as containing mixed content.

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">
            <xml-root-element name="employee" />
            <java-attributes>
                <xml-any-element java-attribute="stuff" xml-mixed="true"/>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>