EclipseLink/DesignDocs/293925/MOXyExtensions/XMLDirectCollectionMapping

XMLDirectCollectionMapping

Requirements

Provide support for XML composite direct 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 direct collection mapping support

We will extend our current xml-element and xml-attribute support to allow direct collection mapping configuration. For example, the following XML metadata snippet would be used to setup a direct collection mapping for 'projectIds':

<xml-element java-attribute="projectIds" xml-path="projectId/text()" />

If projectIds was to be mapped using the grouping element projects/projectId, then the following would be used:

<xml-element java-attribute="projectIds" xml-path="projects/projectId/text()" />

Example:

The following example will demonstrate how to configure XML direct 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<String> projectIds;
    public List<Float> salaries;
    public List<String> privateData;
    public List<String> characterData; 
 
    public List<String> getProjectIds() {
        return projectIds;
    }
 
    public void setProjectIds(List<String> projectIds) {
        this.projectIds = projectIds;
    }
}

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-direct-collection-mapping">
      <attribute-name>projectIds</attribute-name>
      <get-method>getProjectIds</get-method>
      <set-method>setProjectIds</set-method>
      <field name="projects/projectId/text()" xsi:type="node"/>
      <container xsi:type="list-container-policy">
        <collection-type>java.util.Vector</collection-type>
      </container>
      <null-policy xsi:type="null-policy">
        <null-representation-for-xml>EMPTY_NODE</null-representation-for-xml>
      </null-policy>
    </attribute-mapping>
    <attribute-mapping xsi:type="xml-composite-direct-collection-mapping">
      <attribute-name>salaries</attribute-name>
      <read-only>true</read-only>
      <field name="@salaries" 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-direct-collection-mapping">
      <attribute-name>privateData</attribute-name>
      <field name="private-data/entry/text()" 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-direct-collection-mapping">
      <attribute-name>characterData</attribute-name>
      <field name="character-data/entry/text()" xsi:type="node"/>
      <container xsi:type="list-container-policy">
        <collection-type>java.util.Vector</collection-type>
      </container>
      <is-cdata>true</is-cdata>
    </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 empId="101" salaries="123456.78 234567.89">
  <projects>
    <projectId>01</projectId>
    <projectId>10</projectId>
    <projectId/>
    <projectId>11</projectId>
  </projects>
  <private-data>
      <entry>This is some private data</entry>
      <entry>This is more private data</entry>
  </private-data>
  <character-data>
      <entry><![CDATA[<characters>a b c d e f g</characters>]]></entry>
      <entry><![CDATA[<characters>h i j k l m n</characters>]]></entry>
  </character-data>
</employee>

XML Instance Document (write)

<?xml version="1.0" encoding="UTF-8"?>
<employee empId="101">
  <projects>
    <projectId>01</projectId>
    <projectId>10</projectId>
    <projectId/>
    <projectId>11</projectId>
  </projects>
  <private-data>
      <entry>This is some private data</entry>
      <entry>This is more private data</entry>
  </private-data>
  <character-data>
      <entry><![CDATA[<characters>a b c d e f g</characters>]]></entry>
      <entry><![CDATA[<characters>h i j k l m n</characters>]]></entry>
  </character-data>
</employee>

org/example/eclipselink-oxm.xml

This XML file demonstrates configuring XML direct 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-attribute java-attribute="id" xml-path="@empId" />
                <xml-element java-attribute="projectIds" xml-path="projects/projectId/text()">
                    <xml-null-policy null-representation-for-xml="EMPTY_NODE" />
                    <xml-access-methods get-method="getProjectIds" set-method="setProjectIds" />
                </xml-element>
                <xml-attribute java-attribute="salaries" read-only="true" />
                <xml-element java-attribute="privateData" xml-path="private-data/entry/text()" write-only="true" />
                <xml-element java-attribute="characterData" xml-path="character-data/entry/text()" cdata="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