EclipseLink/DesignDocs/293925/MOXyExtensions/XMLCompositeCollectionMapping

XMLCompositeCollectionMapping

Requirements

Provide support for XML composite collection mapping configuration via XML metadata file.

The following should be configurable:

• Path-based mappings
• Positional mappings
• Read only
• Write only
• CDATA
• Get/set method names

Design

Basic XML composite collection mapping support

We will extend our current xml-element and xml-attribute support to allow composite collection mapping configuration. For example, the following XML metadata snippet would be used to setup a composite collection mapping for 'addresses', where the addresses attribute is a List<Address>:

<xml-element java-attribute="addresses" />

If addresses was to be mapped using a grouping element then the following would be used:

<xml-element java-attribute="addresses" xml-path="addresses/address" />

Equivalent annotations

@javax.xml.bind.annotation.XmlAnyElement
@org.eclipse.persistence.oxm.annotations.XmlPath("addresses/address")
public List<Address> addresses;

Example:

The following example will demonstrate how to configure XML composite collection mappings via XML metadata by using xml-element and xml-attribute.

org.example.Employee.java

package org.example;
 
public class Employee {
    public int id;
    public List<Address> addresses;
    public List<Address> readOnlyAddressList;
    public List<Address> writeOnlyAddressList;
 
    public List<Address> getAddresses() {
        return addresses;
    }
 
    public void setAddresses(List<Address> addresses) {
        this.addresses = addresses;
    }
}

org.example.Address.java

package org.example;
 
public class Address {
    public int id;
    public String city;
    public String street;
    public String province;
    public String postalCode;
}

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-direct-mapping">
      <attribute-name>id</attribute-name>
      <field name="@empId" xsi:type="node"/>
    </attribute-mapping>
    <attribute-mapping xsi:type="xml-composite-collection-mapping">
      <attribute-name>addresses</attribute-name>
      <get-method>getAddresses</get-method>
      <set-method>setAddresses</set-method>
      <reference-class>org.example.Address</reference-class>
      <field name="info/c:contact-info/addresses/address" xsi:type="node"/>
      <container xsi:type="list-container-policy">
        <collection-type>java.util.Vector</collection-type>
      </container>
    </attribute-mapping>
    <attribute-mapping xsi:type="xml-composite-collection-mapping">
      <attribute-name>readOnlyAddressList</attribute-name>
      <read-only>true</read-only>
      <reference-class>org.example.Address</reference-class>
      <field name="info/read-only/address" xsi:type="node"/>
      <container xsi:type="list-container-policy">
        <collection-type>java.util.Vector</collection-type>
      </container>
    </attribute-mapping>
    <attribute-mapping xsi:type="xml-composite-collection-mapping">
      <attribute-name>writeOnlyAddressList</attribute-name>
      <reference-class>org.example.Address</reference-class>
      <field name="info/write-only/address" xsi:type="node"/>
      <container xsi:type="list-container-policy">
        <collection-type>java.util.Vector</collection-type>
      </container>
    </attribute-mapping>
  </attribute-mappings>
  <default-root-element>employee</default-root-element>
  <default-root-element-field name="employee"/>
  <namespace-resolver>
    <namespaces>
      <namespace>
        <prefix>c</prefix>
        <namespace-uri>http://www.example.com/contacts</namespace-uri>
      </namespace>
    </namespaces>
  </namespace-resolver>
</class-mapping-descriptor>

XML Instance Document (read)

<?xml version="1.0" encoding="UTF-8"?>
<ns0:employee empId="101" xmlns:c="http://www.example.com/contacts" xmlns:ns0="http://www.example.com/employees">
    <info>
        <c:contact-info>
            <addresses>
                <address id="67">
                    <city>Kanata</city>
                    <street>66 Lakview Drive</street>
                    <province>ON</province>
                    <postalCode>K2M2K7</postalCode>
                </address>
                <address/>
                <address id="76">
                    <city>Ottawa</city>
                    <street>45 O'Connor St.</street>
                    <province>ON</province>
                    <postalCode>K1P1A4</postalCode>
                </address>
            </addresses>
        </c:contact-info>
        <read-only>
            <address id="66">
                <city>Woodlawn</city>
                <street>465 Bayview Dr.</street>
                <province>ON</province>
                <postalCode>K0A3M0</postalCode>
            </address>
        </read-only>
        <write-only>
            <address id="77">
                <city>Woodlawn</city>
                <street>463 Bayview Dr.</street>
                <province>ON</province>
                <postalCode>K0A3M0</postalCode>
            </address>
        </write-only>
    </info>
</ns0:employee>

XML Instance Document (write)

<?xml version="1.0" encoding="UTF-8"?>
<ns0:employee empId="101" xmlns:c="http://www.example.com/contacts" xmlns:ns0="http://www.example.com/employees">
    <info>
        <c:contact-info>
            <addresses>
                <address id="67">
                    <city>Kanata</city>
                    <street>66 Lakview Drive</street>
                    <province>ON</province>
                    <postalCode>K2M2K7</postalCode>
                </address>
                <address/>
                <address id="76">
                    <city>Ottawa</city>
                    <street>45 O'Connor St.</street>
                    <province>ON</province>
                    <postalCode>K1P1A4</postalCode>
                </address>
            </addresses>
        </c:contact-info>
        <write-only>
            <address id="77">
                <city>Woodlawn</city>
                <street>463 Bayview Dr.</street>
                <province>ON</province>
                <postalCode>K0A3M0</postalCode>
            </address>
        </write-only>
    </info>
</ns0:employee>

org/example/eclipselink-oxm.xml

This XML file demonstrates configuring XML composite 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">
    <xml-schema namespace="http://www.example.com/employees" >
        <xml-ns namespace-uri="http://www.example.com/contacts" prefix="c"/>
    </xml-schema>
    <java-types>
        <java-type name="org.example.Employee">
            <xml-root-element name="employee" />
            <java-attributes>
                <xml-attribute java-attribute="id" xml-path="@empId" />
                <xml-element java-attribute="addresses" xml-path="info/c:contact-info/addresses/address">
                    <xml-null-policy null-representation-for-xml="EMPTY_NODE" />
                    <xml-access-methods get-method="getAddresses" set-method="setAddresses" />
                </xml-element>
                <xml-element java-attribute="readOnlyAddressList" xml-path="info/read-only/address" read-only="true" />
                <xml-element java-attribute="writeOnlyAddressList" xml-path="info/write-only/address" write-only="true" />
            </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