EclipseLink/DesignDocs/293925/MOXyExtensions/XmlChoiceCollectionMapping

XMLChoiceCollectionMapping

Requirements

Provide support for XML choice collection mapping configuration via XML metadata file. We currently support Xml choice collection 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 collection.

Design

Basic XML choice collection mapping support

We will extend our current xml-elements support to allow choice collection mapping configuration. For example, the following XML metadata snippet would be used to setup a choice collection mapping for 'things' (where things is a List<Object> in the object model):

<xml-elements java-attribute="things">
    <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="things">
    <xml-access-methods get-method="getThings" set-method="setThings" />
    <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 List<Object> things;

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 collection mappings via XML metadata by using xml-elements.

org.example.Employee.java

package org.example;
 
public class Employee {
    public List<Object> things;
    public List<Object> readOnlyThings;
    public List<Object> writeOnlyThings;
 
    public List<Object> getThings() {
        return things;
    }
 
    public void setThings(List<Object> things) {
        this.things = things;
    }
}

XML Instance Document (read)

<?xml version="1.0" encoding="UTF-8"?>
<employee>
    <things>
        <my-integer>66</my-integer>
        <my-integer>99</my-integer>
        <my-float>101.1</my-float>
    </things>
    <my-read-only-float>88.8</my-read-only-float>
    <my-read-only-integer>77</my-read-only-integer>
    <stuff>
        <my-write-only-integer>3</my-write-only-integer>
    </stuff>
</employee>

XML Instance Document (write)

<?xml version="1.0" encoding="UTF-8"?>
<employee>
    <things>
        <my-integer>66</my-integer>
        <my-integer>99</my-integer>
        <my-float>101.1</my-float>
    </things>
    <stuff>
        <my-write-only-integer>3</my-write-only-integer>
    </stuff>
</employee>

org/example/eclipselink-oxm.xml

This XML file demonstrates configuring XML choice collection 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="things">
                    <xml-access-methods get-method="getThings" set-method="setThings" />
                    <xml-element type="java.lang.Integer" xml-path="things/my-integer/text()" />
                    <xml-element type="java.lang.Float" xml-path="things/my-float/text()" />
                </xml-elements>
                <xml-elements java-attribute="readOnlyThings" 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="writeOnlyThings" 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-element-wrapper name="stuff" />
                </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

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