EclipseLink/DesignDocs/293925/MOXyExtensions/XmlObjectReferenceMapping

XMLObjectReferenceMapping

Requirements

Provide support for XML object reference mapping configuration via XML metadata file.

The following should be configurable:

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

Design

Basic XML object reference mapping support

We will extend our current xml-element and xml-attribute support to allow object reference mapping configuration. For example, the following XML metadata snippet would be used to setup an object reference mapping for 'workAddress':

<xml-element java-attribute="workAddress" xml-idref="true" />

Where the following exists in Address:

<xml-attribute java-attribute="id" xml-id="true" required="true" />

If workAddress was to be mapped to an element named work-address-id, then the following would be used:

<xml-element java-attribute="workAddress" xml-path="work-address-id/text()" xml-idref="true" />

Where the following exists in Address:

<xml-attribute java-attribute="id" xml-id="true" required="true" />

Read Only

The following demonstrates how an object reference mapping can be set as read-only:

<xml-attribute java-attribute="workAddress" xml-idref="true" read-only="true">

Write Only

The following demonstrates how an object reference mapping can be set as write-only:

<xml-attribute java-attribute="workAddress" xml-idref="true" write-only="true">

Equivalent annotations

Employee:
@javax.xml.bind.annotation.XmlIDREF
public Address workAddress;
 
Address:
@javax.xml.bind.annotation.XmlID
public String id;

Example:

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

org.example.Root.java

package org.example;
 
public class Root {
    public List<Employee> employees;
    public List<Address> addresses;
}

org.example.Employee.java

package org.example;
 
public class Employee {
    public Address workAddress;
 
    public Address getWorkAddress() {
        return workAddress;
    }
 
    public void setWorkAddress(Address workAddress) {
        this.workAddress = workAddress;
    }
}

org.example.Address.java

package org.example;
 
public class Address {
    public String id;
}

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-object-reference-mapping">
      <attribute-name>workAddress</attribute-name>
      <get-method>getWorkAddress</get-method>
      <set-method>setWorkAddress</set-method>
      <source-to-target-key-field-association>
        <field-reference>
          <source-field name="contact-info/work-address/@work-address-id" xsi:type="node"/>
          <target-field name="@aid" xsi:type="node"/>
        </field-reference>
      </source-to-target-key-field-association>
      <source-to-target-key-fields>
        <field name="contact-info/work-address/@work-address-id" xsi:type="node"/>
      </source-to-target-key-fields>
    </attribute-mapping>
  </attribute-mappings>
  <default-root-element>employee</default-root-element>
  <default-root-element-field name="employee"/>
</class-mapping-descriptor>
 
<class-mapping-descriptor xsi:type="xml-class-mapping-descriptor">
  <class>org.example.Address</class>
  <alias>Address</alias>
  <primary-key>
    <field name="@aid" xsi:type="node"/>
  </primary-key>
  <attribute-mappings>
    <attribute-mapping xsi:type="xml-direct-mapping">
      <attribute-name>id</attribute-name>
      <field name="@aid" xsi:type="node"/>
    </attribute-mapping>
  </attribute-mappings>
  <default-root-element>address</default-root-element>
  <default-root-element-field name="address"/>
</class-mapping-descriptor>

XML Instance Document

<?xml version='1.0' encoding='UTF-8'?>
<document-root>
    <employees>
        <employee>
            <contact-info>
                <work-address work-address-id="101" />
            </contact-info>
        </employee>
    </employees>
    <addresses>
        <address aid="100" />
        <address aid="101" />
        <address aid="102" />
    </addresses>
</document-root>

org/example/eclipselink-oxm.xml

This XML file demonstrates configuring XML object reference 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.Root">
            <xml-root-element name="document-root" />
            <java-attributes>
                <xml-element java-attribute="employees" xml-path="employee" />
                <xml-element java-attribute="addresses" xml-path="addresses/address" />
            </java-attributes>
        </java-type>
        <java-type name="org.example.Employee">
            <java-attributes>
                <xml-attribute java-attribute="workAddress" xml-path="contact-info/work-address/@work-address-id" xml-idref="true">
                    <xml-access-methods get-method="getWorkAddress" set-method="setWorkAddress" />
                </xml-attribute>
            </java-attributes>
        </java-type>
        <java-type name="org.example.Address">
            <java-attributes>
                <xml-attribute java-attribute="id" xml-path="@aid" xml-id="true" required="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