EclipseLink/DesignDocs/293925/MOXyExtensions/XmlChoiceObjectMapping

XMLChoiceObjectMapping

Requirements

Provide support for XML choice object mapping configuration via XML metadata file. We currently support Xml choice mappings via the xml-elements structure. This structure will be extended to allow xml-access-methods, read-only, etc. to be set for the choice.

Design

Basic XML choice object mapping support

We will extend our current xml-elements support to allow choice mapping configuration. We will need to modify the XSD such that xml-access-methods, read-only, etc. can be set on xml-elements. For example, the following XML metadata snippet would be used to setup a choice object mapping for 'thing':

<xml-elements java-attribute="thing">
    <xml-element type="java.lang.Integer" name="my-integer" />
    <xml-element type="java.lang.Float" name="my-float" />
</xml-elements>

Path-based mapping support

Path-based mappings will be supported via xml-path attribute on the xml-element entries within the xml-elements structure. For example:

<xml-elements java-attribute="thing">
    <xml-access-methods get-method="getThing" set-method="setThing" />
    <xml-element type="java.lang.Integer" xml-path="integers/my-integer/text()" />
    <xml-element type="java.lang.Float" xml-path="floats/my-float/text()" />
</xml-elements>

Equivalent annotations

@javax.xml.bind.annotation.XmlElements {
    @javax.xml.bind.annotation.XmlElement(type=java.lang.Integer.class),
    @javax.xml.bind.annotation.XmlElement(type=java.lang.Float.class)
}
@org.eclipse.persistence.oxm.annotations.XmlPaths* {
    @org.eclipse.persistence.oxm.annotations.XmlPath("integers/my-integer"),*
    @org.eclipse.persistence.oxm.annotations.XmlPath("floats/my-float")*
}
public Object thing;

Note that the XmlPaths and XmlPath annotations do not exist and are intended for example purposes only.

Example:

The following example will demonstrate how to configure XML choice object mappings via XML metadata by using xml-elements.

org.example.Employee.java

package org.example;
 
public class Employee {
    public Object thing;
    public Object readOnlyThing;
    public Object writeOnlyThing;
 
    public Object getThing() {
        return thing;
    }
 
    public void setThing(Object thing) {
        this.thing = thing;
    }
}

Deployment XML

<class-mapping-descriptor xsi:type="xml-class-mapping-descriptor">
  <class>org.example.Employee</class>
  <alias>Employee</alias>
  <attribute-mappings>
    <attribute-mapping xsi:type="xml-choice-object-mapping">
      <attribute-name>thing</attribute-name>
      <get-method>getThing</get-method>
      <set-method>setThing</set-method>
      <field-to-class-association>
        <xml-field name="integers/my-integer/text()"/>
        <class-name>java.lang.Integer</class-name>
      </field-to-class-association>
      <field-to-class-association>
        <xml-field name="floats/my-float/text()"/>
        <class-name>java.lang.Float</class-name>
      </field-to-class-association>
    </attribute-mapping>
    <attribute-mapping xsi:type="xml-choice-object-mapping">
      <attribute-name>readOnlyThing</attribute-name>
      <read-only>true</read-only>
      <field-to-class-association>
        <xml-field name="my-read-only-float"/>
        <class-name>java.lang.Float</class-name>
      </field-to-class-association>
      <field-to-class-association>
        <xml-field name="my-read-only-integer"/>
        <class-name>java.lang.Integer</class-name>
      </field-to-class-association>
    </attribute-mapping>
    <attribute-mapping xsi:type="xml-choice-object-mapping">
      <attribute-name>writeOnlyThing</attribute-name>
      <field-to-class-association>
        <xml-field name="my-write-only-float"/>
        <class-name>java.lang.Float</class-name>
      </field-to-class-association>
      <field-to-class-association>
        <xml-field name="my-write-only-integer"/>
        <class-name>java.lang.Integer</class-name>
      </field-to-class-association>
    </attribute-mapping>
  </attribute-mappings>
  <default-root-element>employee</default-root-element>
  <default-root-element-field name="employee"/>
</class-mapping-descriptor>

XML Instance Document (read)

<?xml version="1.0" encoding="UTF-8"?>
<employee>
    <integers>
        <my-integer>66</my-integer>
    </integers>
    <my-read-only-float>66.66</my-read-only-float>
    <my-write-only-integer>66</my-write-only-integer>
</employee>

XML Instance Document (write)

<?xml version="1.0" encoding="UTF-8"?>
<employee>
    <integers>
        <my-integer>66</my-integer>
    </integers>
    <my-write-only-integer>66</my-write-only-integer>
</employee>

org/example/eclipselink-oxm.xml

This XML file demonstrates configuring XML choice object mappings on 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-elements java-attribute="thing">
                    <xml-access-methods get-method="getThing" set-method="setThing" />
                    <xml-element type="java.lang.Integer" xml-path="integers/my-integer/text()" />
                    <xml-element type="java.lang.Float" xml-path="floats/my-float/text()" />
                </xml-elements>
                <xml-elements java-attribute="readOnlyThing" read-only="true">
                    <xml-element type="java.lang.Integer" name="my-read-only-integer" />
                    <xml-element type="java.lang.Float" name="my-read-only-float" />
                </xml-elements>
                <xml-elements java-attribute="writeOnlyThing" write-only="true">
                    <xml-element type="java.lang.Integer" name="my-write-only-integer" />
                    <xml-element type="java.lang.Float" name="my-write-only-float" />
                </xml-elements>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

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
1	D.McCann	How do we handle xml-path for choice mappings? Should the xml-elements have an xml-path, and the xml-element entries not have them, or should xml-path apply to both?
2	D.McCann	What is the expected behavior if one or more xml-element entries contains extended mapping information such as xml-access-methods, xml-null-policy etc.?

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