Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/DesignDocs/293925/MOXyExtensions/XMLDirectMapping"

(Deployment XML)
(XML Instance Document)
Line 153: Line 153:
 
<source lang="xml">
 
<source lang="xml">
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
<employee id="66" xmlns="http://www.example.com/employees" xmlns:prj="http://www.example.com/projects">
+
<employee id="66" salary="123456.78" xmlns="http://www.example.com/employees" xmlns:prj="http://www.example.com/projects">
 
     <projects>
 
     <projects>
 
         <prj:project managerId="99">XML External Metadata Support</prj:project>
 
         <prj:project managerId="99">XML External Metadata Support</prj:project>
Line 167: Line 167:
 
         <data>data two</data>
 
         <data>data two</data>
 
     </pieces-of-data>
 
     </pieces-of-data>
 +
    <private-data>This is some private data</private-data>
 
</employee>
 
</employee>
 
</source>
 
</source>

Revision as of 16:02, 22 February 2010

XMLDirectMapping

Requirements

Provide support for XML direct mapping configuration via XML metadata file.

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


The following should be configurable:

  • Path-based mappings
  • Positional Mappings
  • Read only (boolean)
  • Write only (boolean)
  • CDATA (boolean)
  • Converters
  • Default null value
  • Null policy
  • Get/set method names

Design

Basic XML direct mapping support

We will use the xml-attribute, xml-element and xml-value 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" />

The same example mapped to a simple type:

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

Path-based mapping support

We will support path-based mappings on xml-attribute and xml-element by making use of the xml-element-wrapper structure. Path-based mappings will not apply to xml-value. An example of configuring a path-based XML direct mapping can be found below, and additional information/examples here.

Positional Mappings

Positional mappings will be supported on xml-element. An example of configuring a positional XML direct mapping can be found below and additional information/examples here. Note that positional mappings cannot be applied to xml-attribute or xml-value.

Read Only

Read only will be supported via boolean attribute on xml-attribute, xml-element and xml-value. An example of configuring a read only XML direct mapping can be found here.

Write Only

Write only will be supported via boolean attribute on xml-attribute, xml-element and xml-value. An example of configuring a write only XML direct mapping can be found here.

CDATA

CDATA will be supported via boolean attribute on xml-element and xml-value. An example of configuring a XML direct mapping as CDATA can be found here. Note that CDATA cannot be applied to xml-attribute.

Default Null Value

To support default null value configuration, a sub-element will be added to xml-attribute, xml-element and xml-value. An example of configuring the null value on a XML direct mapping, as well as the proposed schema change, can be found here.

Get/Set Method Names

The get/set method names on xml-attribute, xml-element and xml-value will be configurable via sub-element. An example of configuring the accessor methods on a XML direct mapping can be found below, and additional examples and proposed schema changes can be found here.

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;
    public String data1;
    public String data2;
    public double salary;
    public String privateData;
 
 
    String getProject() {
        return projectName; 
    }
 
    void setProject(String name) {
        projectName = name;
    }
}

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="info/personal-info/first-name/text()" xsi:type="node"/>
        </attribute-mapping>
        <attribute-mapping xsi:type="xml-direct-mapping">
           <attribute-name>lastName</attribute-name>
           <field name="info/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>
           <get-method>getProject</get-method>
           <set-method>setProject</set-method>
           <field name="projects/prj:project/text()" xsi:type="node"/>
        </attribute-mapping>
        <attribute-mapping xsi:type="xml-direct-mapping">
            <attribute-name>data1</attribute-name>
            <field name="pieces-of-data/data[1]/text()" xsi:type="node"/>
        </attribute-mapping>
        <attribute-mapping xsi:type="xml-direct-mapping">
            <attribute-name>data2</attribute-name>
            <field name="pieces-of-data/data[2]/text()" xsi:type="node"/>
        </attribute-mapping>
        <attribute-mapping xsi:type="xml-direct-mapping">
            <attribute-name>salary</attribute-name>
            <read-only>true</read-only>
            <field name="@salary" xsi:type="node"/>
        </attribute-mapping>
        <attribute-mapping xsi:type="xml-direct-mapping">
            <attribute-name>privateData</attribute-name>
            <field name="private-data/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" salary="123456.78" xmlns="http://www.example.com/employees" xmlns:prj="http://www.example.com/projects">
    <projects>
        <prj:project managerId="99">XML External Metadata Support</prj:project>
    </projects>
    <info>
        <personal-info>
            <first-name>Joe</first-name>
            <last-name>Oracle</last-name>
        </personal-info>
    </info>
    <pieces-of-data>
        <data>data one</data>
        <data>data two</data>
    </pieces-of-data>
    <private-data>This is some private data</private-data>
</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="info/personal-info" />
                </xml-element>
                <xml-element java-attribute="lastName" name="last-name" >
                    <xml-element-wrapper name="info/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-access-methods get-method="getProject" set-method="setProject" />
                </xml-element>
                <xml-element java-attribute="data2" name="data[2]">
                    <xml-element-wrapper name="pieces-of-data" />
                </xml-element>
                <xml-element java-attribute="data1" name="data[1]">
                    <xml-element-wrapper name="pieces-of-data" />
                </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

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

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.

Back to the top