EclipseLink/DesignDocs/293925/MOXyExtensions/XMLDirectMapping

XMLDirectMapping

Provide support for XML direct mappings via xml-element and xml-attribute.

Open Issues

• XPath - should we overload the name attribute on xml-attribute and xml-element to set the XPath, or create a new attribute xml-path?
  • The current approach is to use xml-path and NOT overload name, as name is not intended to be used in this manner

Example: XPath Use With XMLDirectMapping

The following example will demonstrate how to configure an XMLDirectMapping using XPaths via XML Metadata:

org.example.Employee.java

package org.example;
 
public class Employee {
    public int empId;
    public int mgrId;
    public String firstName;
    public String lastName;
    public String projectName;
}

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>empId</attribute-name>
            <field name="@id" xsi:type="node"/>
        </attribute-mapping>
        <attribute-mapping xsi:type="xml-direct-mapping">
            <attribute-name>firstName</attribute-name>
            <field name="name/first-name/text()" xsi:type="node"/>
        </attribute-mapping>
        <attribute-mapping xsi:type="xml-direct-mapping">
            <attribute-name>lasstName</attribute-name>
            <field name="name/last-name/text()" xsi:type="node"/>
        </attribute-mapping>
        <attribute-mapping xsi:type="xml-direct-mapping">
            <attribute-name>projectName</attribute-name>
            <field name="projects/prj:project/text()" xsi:type="node"/>
        </attribute-mapping>
        <attribute-mapping xsi:type="xml-direct-mapping">
            <attribute-name>mgrId</attribute-name>
            <field name="projects/prj:project/@managerId" xsi:type="node"/>
        </attribute-mapping>
    </attribute-mappings>
    <descriptor-type>aggregate</descriptor-type>
    <default-root-element>employee</default-root-element>
    <default-root-element-field name="employee" xsi:type="node"/>
    <namespace-resolver>
        <namespaces>
            <namespace>
                <prefix>prj</prefix>
                <namespace-uri>http://www.example.com/projects</namespace-uri>
            </namespace>
        </namespaces>
        <default-namespace-uri>http://www.example.com/employees</default-namespace-uri>
    </namespace-resolver>
</class-mapping-descriptor>

XML Instance Document

<?xml version="1.0" encoding="UTF-8"?>
<employee id="66" xmlns="http://www.example.com/employees" xmlns:prj="http://www.example.com/projects">
    <name>
        <first-name>Joe</first-name>
        <last-name>Black</last-name>
    </name>
    <projects>
        <prj:project managerId="99">XML External Metadata Support</prj:project>
    </projects>
</employee>

XML Metadata Option 1: overload name attribute on xml-element/xml-attribute

<?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/projects" prefix="prj" />
    </xml-schema>
    <java-types>
        <java-type name="org.example.Employee">
            <xml-root-element name="employee" />
            <java-attributes>
                <xml-attribute java-attribute="empId" name="id" />
                <xml-attribute java-attribute="mgrId" name="projects/prj:project/managerId" />
                <xml-element java-attribute="firstName" name="name/first-name" />
                <xml-element java-attribute="lastName" name="name/last-name" />
                <xml-element java-attribute="projectName" name="projects/prj:project" />
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

XML Metadata Option 2: add an xml-path attribute to xml-element/xml-attribute

<?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/projects" prefix="prj" />
    </xml-schema>
    <java-types>
        <java-type name="org.example.Employee">
            <xml-root-element name="employee" />
            <java-attributes>
                <xml-attribute java-attribute="empId" name="id" />
                <xml-attribute java-attribute="mgrId" xml-path="projects/prj:project/managerId" />
                <xml-element java-attribute="firstName" xml-path="name/first-name" />
                <xml-element java-attribute="lastName" xml-path="name/last-name" />
                <xml-element java-attribute="projectName" name="projects/prj:project" />
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

XML Metadata Option 3: overload name</name> attribute on xml-element-wrapper and enable use with non-collections and xml-attribute

<?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/projects" prefix="prj" />
    </xml-schema>
    <java-types>
        <java-type name="org.example.Employee">
            <xml-root-element name="employee" />
            <java-attributes>
                <xml-attribute java-attribute="empId" name="id" />
                <xml-attribute java-attribute="mgrId" name="managerId">
                    <xml-element-wrapper name="projects/prj:project" />
                </xml-attribute>
                <xml-element java-attribute="firstName" name="first-name">
                    <xml-element-wrapper name="name" />
                </xml-element>
                <xml-element java-attribute="lastName" name="last-name">
                    <xml-element-wrapper name="name" />
                </xml-element>
                <xml-element java-attribute="projectName" name="prj:project">
                    <xml-element-wrapper name="projects" />
                </xml-attribute>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

XML Metadata Option 4: add an <code>xml-path attribute to xml-element-wrapper and enable use with non-collections and xml-attribute

<?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/projects" prefix="prj" />
    </xml-schema>
    <java-types>
        <java-type name="org.example.Employee">
            <xml-root-element name="employee" />
            <java-attributes>
                <xml-attribute java-attribute="empId" name="id" />
                <xml-attribute java-attribute="mgrId" name="managerId">
                    <xml-element-wrapper xml-path="projects/prj:project" />
                </xml-attribute>
                <xml-element java-attribute="firstName" name="first-name">
                    <xml-element-wrapper xml-path="name" />
                </xml-element>
                <xml-element java-attribute="lastName" name="last-name">
                    <xml-element-wrapper xml-path="name" />
                </xml-element>
                <xml-element java-attribute="projectName" name="prj:project">
                    <xml-element-wrapper xml-path="projects" />
                </xml-attribute>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>