XMLDirectMapping

Requirements

Provide support for XML direct mappings.

The following structures are to be extended to support XML direct mapping configuration:

Path-based mappings must be supported. Design notes are located here.

The following should be configurable:

Converter
Get/set method names
Read only (boolean)
Write only (boolean)
Null policy
Default null value
CDATA (boolean)

Design

Basic XML direct mapping support

We will use the xml-attribute and xml-element structures to support direct mappings. For example, the following XML metadata snippet would be used to setup a direct mapping for an empId attribute:

<xml-attribute java-attribute="empId" />

If empId was to be mapped to id, then the following would be used:

<xml-attribute java-attribute="empId" name="id" />

The same example mapped to an id element:

<xml-element java-attribute="empId" name="id" />

Path-based mapping support

Basic configuration

We will support path-based mappings by making use of the xml-element-wrapper structure. The current constraints on xml-element-wrapper that it is only applicable to multi-valued properties and not for use with <xml-attribute> will be removed. The path will be set by overloading the name attribute. For example, the following XML metadata snippet would be used to setup a direct mapping that maps firstName to personal-info/name/first-name:

<xml-element java-attribute="firstName" name="first-name">
    <xml-element-wrapper name="personal-info/name" />
</xml-element>

Positional Paths

Positional paths will be supported. For example, the following would be used to create a mapping to street in the second occurrence of address:

<xml-element java-attribute="street">
    <xml-element-wrapper name="addresses/address[2]" />
</xml-element>

Or:

<xml-element java-attribute="street">
    <xml-element-wrapper name="addresses/address.2" />
</xml-element>

Optional Elements

The following optional elements are applicable to xml-element-wrapper:

namespace
nillable
required

Namespace

If namespace is set, it will be applied to any path element that is not prefixed. For example, the following:

<?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/default">
        <xml-ns namespace-uri="http://www.example.com/employees" prefix="emp"/>
        <xml-ns namespace-uri="http://www.example.com/projects" prefix="prj"/>
    </xml-schema>
    <java-types>
        <java-type name="org.example.Employee">
            <java-attributes>
                <xml-element java-attribute="firstName">
                    <xml-element-wrapper name="prj:info/personal-info/name" namespace="http://www.example.com/employees" />
                </xml-element>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Would be equivalent to:

<?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/default">
        <xml-ns namespace-uri="http://www.example.com/employees" prefix="emp"/>
        <xml-ns namespace-uri="http://www.example.com/projects" prefix="prj"/>
    </xml-schema>
    <java-types>
        <java-type name="org.example.Employee">
            <java-attributes>
                <xml-element java-attribute="firstName">
                    <xml-element-wrapper name="prj:info/emp:personal-info/emp:name" />
                </xml-element>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Nillable & Required

If nillable or required are set, they will be applied to the last element in the path. For example, given the following XML metadata file:

<?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">
            <java-attributes>
                <xml-element java-attribute="firstName" name="first-name">
                    <xml-element-wrapper name="info/personal-info" nillable="true" required="true" />
                </xml-element>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Would result in the following schema:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <xsd:complexType name="employee">
      <xsd:sequence>
         <xsd:element name="info">
            <xsd:complexType>
               <xsd:sequence>
                  <xsd:element name="personal-info" minOccurs="1" nillable="true">
                     <xsd:complexType>
                        <xsd:sequence>
                           <xsd:element name="first-name" type="xsd:string" />
                        </xsd:sequence>
                     </xsd:complexType>
                  </xsd:element>
               </xsd:sequence>
            </xsd:complexType>
         </xsd:element>
      </xsd:sequence>
   </xsd:complexType>
   <xsd:element name="employee" type="employee" />
</xsd:schema>

Read only

Read only will be supported via boolean attribute on xml-attribute and xml-element, i.e.:

<xml-attribute java-attribute="salary" read-only="true" />

CDATA

CDATA will be supported via boolean attribute on xml-attribute and xml-element, i.e.:

<xml-element java-attribute="characterData" cdata="true" />

Example

The following example will demonstrate how to configure XML direct mappings via XML metadata.

org.example.Employee.java

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

Deployment XML

<class-mapping-descriptor xsi:type="xml-class-mapping-descriptor">
    <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="personal-info/first-name/text()" xsi:type="node"/>
        </attribute-mapping>
        <attribute-mapping xsi:type="xml-direct-mapping">
           <attribute-name>lastName</attribute-name>
           <field name="personal-info/last-name/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-mapping xsi:type="xml-direct-mapping">
           <attribute-name>projectName</attribute-name>
           <field name="projects/prj:project/text()" 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">
    <personal-info>
        <first-name>Joe</first-name>
        <last-name>Black</last-name>
    </personal-info>
    <projects>
        <prj:project managerId="99">XML External Metadata Support</prj:project>
    </projects>
</employee>

org/example/eclipselink-oxm.xml

This XML file demonstrates configuring XML direct 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/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-element java-attribute="firstName" name="first-name">
                    <xml-element-wrapper name="personal-info" />
                </xml-element>
                <xml-element java-attribute="lastName" name="last-name" >
                    <xml-element-wrapper name="personal-info" />
                </xml-element>
                <xml-attribute java-attribute="mgrId" name="managerId" >
                    <xml-element-wrapper name="projects/prj:project" />
                </xml-attribute>
                <xml-element java-attribute="projectName" name="project" namespace="http://www.example.com/projects" >
                    <xml-element-wrapper name="projects" />
                </xml-element>
            </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	Two possible ways to allow a path-based mapping to be configured are being considered: `xml-attribute/xml-element` or `xml-element-wrapper`. Which is preferred? Design note are located here.
2	D.McCann	Three possible ways to set the path for a mapping are being considered: `name` overload vs. `xpath` vs. `name` + `grouping-element`. Which is preferred? Design notes are located here.
3	D.McCann	What is the expected behavior when `namespace` is set on an `xml-element-wrapper` that has a path set?
4	D.McCann	What is the expected behavior when `required` is set on an `xml-element-wrapper` that has a path set?
5	D.McCann	What is the expected behavior when `nillable` is set on an `xml-element-wrapper` that has a path set?
6	D.McCann	How can we support positional mappings?

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
1	Two possible ways to allow a path-based mapping to be configured are being considered: `xml-attribute/xml-element` or `xml-element-wrapper`	`xml-element-wrapper` will be extended to handle multi-level paths, and enabled for use with `xml-attribute` and single-valued properties.
2	Three possible ways to set the path for a mapping are being considered: `name` overload vs. `xpath` vs. `name` + `grouping-element`	`name` will be overloaded.
3	What is the expected behavior when `namespace` is set on an `xml-element-wrapper` that has a path set?	If `namespace` is set, it will be applied to any path element that is not prefixed.
4	What is the expected behavior when `required` is set on an `xml-element-wrapper` that has a path set?	If `required` is set, it will be applied to the last element in the path.
5	What is the expected behavior when `nillable` is set on an `xml-element-wrapper` that has a path set?	If `nillable` is set, it will be applied to the last element in the path.

Future Considerations

During the research for this project the following items were identified as out of scope but are captured here as potential future enhancements. If agreed upon during the review process these should be logged in the bug system.

For issue #2 above, it may be useful to add an additional attribute such that users who do not wish use the name attribute in a non-standard way are able to set a multi-level path.

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

EclipseLink/DesignDocs/293925/MOXyExtensions/XMLDirectMapping

Contents

XMLDirectMapping

Requirements

Design

Basic XML direct mapping support

Path-based mapping support

Basic configuration

Positional Paths

Optional Elements

Namespace

Nillable & Required

Read only

CDATA

Example

org.example.Employee.java

Deployment XML

XML Instance Document

org/example/eclipselink-oxm.xml

Open Issues

Decisions

Future Considerations

Breadcrumbs

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

EclipseLink/DesignDocs/293925/MOXyExtensions/XMLDirectMapping

Contents

XMLDirectMapping

Requirements

Design

Basic XML direct mapping support

Path-based mapping support

Basic configuration

Positional Paths

Optional Elements

Namespace

Nillable & Required

Read only

CDATA

Example

org.example.Employee.java

Deployment XML

XML Instance Document

org/example/eclipselink-oxm.xml

Open Issues

Decisions

Future Considerations