Skip to main content

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.

Jump to: navigation, search

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

(→‎org/example/eclipselink-oxm.xml)
(→‎org/example/eclipselink-oxm.xml)
Line 1: Line 1:
 
<div style="border: 1px solid rgb(0, 0, 0); margin: 5px; padding: 5px; float: right;">__TOC__</div>  
 
<div style="border: 1px solid rgb(0, 0, 0); margin: 5px; padding: 5px; float: right;">__TOC__</div>  
−
= XMLDirectMapping (page under construction) =
+
= XMLDirectMapping =
  
 
== Requirements ==
 
== Requirements ==
−
Provide support for XML direct mappings.
+
Provide support for XML direct mappings.
  
 
The following structures are to be extended to support XML direct mapping configuration:
 
The following structures are to be extended to support XML direct mapping configuration:
Line 9: Line 9:
 
* <code>xml-element</code>
 
* <code>xml-element</code>
  
−
[http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/PathBasedMappings Path-based] mappings must be supported.
 
  
−
=== The following information must be configurable via XML metadata ===
+
Path-based mappings must be supported.  Design notes are located [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/PathBasedMappings here].
−
<source lang="xml">
+
 
−
<xml-direct-mapping xmlns="http://www.eclipse.org/eclipselink/xsds/persistence">
+
The following should be configurable:
−
<attribute-name>String</attribute-name>
+
* Null policy
−
<read-only>false</read-only>
+
* Get/set method names
−
<get-method>String</get-method>
+
* Read only
−
<set-method>String</set-method>
+
* Attribute classification
−
<properties>
+
* Default null value
−
<property name="String">
+
* CDATA
−
<value>Text</value>
+
* Converter
−
</property>
+
−
<property name="String">
+
−
<value>Text</value>
+
−
</property>
+
−
</properties>
+
−
<field name="String"/>
+
−
<null-value>String</null-value>
+
−
<converter/>
+
−
<attribute-classification>String</attribute-classification>
+
−
<is-cdata>1</is-cdata>
+
−
<null-policy>
+
−
<xsi-nil-represents-null>false</xsi-nil-represents-null>
+
−
<empty-node-represents-null>false</empty-node-represents-null>
+
−
<null-representation-for-xml>XSI_NIL</null-representation-for-xml>
+
−
</null-policy>
+
−
</xml-direct-mapping>
+
−
</source>
+
  
 
== Example ==
 
== Example ==
Line 65: Line 47:
 
         <attribute-mapping xsi:type="xml-direct-mapping">
 
         <attribute-mapping xsi:type="xml-direct-mapping">
 
           <attribute-name>firstName</attribute-name>
 
           <attribute-name>firstName</attribute-name>
−
           <field name="first-name/text()" xsi:type="node"/>
+
           <field name="personal-info/first-name/text()" xsi:type="node"/>
 
         </attribute-mapping>
 
         </attribute-mapping>
 
         <attribute-mapping xsi:type="xml-direct-mapping">
 
         <attribute-mapping xsi:type="xml-direct-mapping">
 
           <attribute-name>lastName</attribute-name>
 
           <attribute-name>lastName</attribute-name>
−
           <field name="last-name/text()" xsi:type="node"/>
+
           <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>
 
         <attribute-mapping xsi:type="xml-direct-mapping">
 
         <attribute-mapping xsi:type="xml-direct-mapping">
 
           <attribute-name>projectName</attribute-name>
 
           <attribute-name>projectName</attribute-name>
−
           <field name="prj:project/text()" xsi:type="node"/>
+
           <field name="projects/prj:project/text()" xsi:type="node"/>
 
         </attribute-mapping>
 
         </attribute-mapping>
 
     <attribute-mappings>
 
     <attribute-mappings>
Line 95: Line 81:
 
<?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" xmlns="http://www.example.com/employees" xmlns:prj="http://www.example.com/projects">
−
     <first-name>Joe</first-name>
+
     <name>
−
    <last-name>Black</last-name>
+
        <first-name>Joe</first-name>
−
     <prj:project>XML External Metadata Support</prj:project>
+
        <last-name>Black</last-name>
 +
     </name>
 +
    <projects>
 +
        <prj:project managerId="99">XML External Metadata Support</prj:project>
 +
    </projects>
 
</employee>
 
</employee>
 
</source>
 
</source>
Line 114: Line 104:
 
             <java-attributes>
 
             <java-attributes>
 
                 <xml-attribute java-attribute="empId" name="id" />
 
                 <xml-attribute java-attribute="empId" name="id" />
−
                 <xml-element java-attribute="firstName" name="first-name" />
+
                 <xml-element java-attribute="firstName" name="first-name">
−
                 <xml-element java-attribute="lastName" name="last-name" />
+
                    <xml-element-wrapper name="personal-info" />
−
                 <xml-element java-attribute="projectName" name="prj:project" />
+
                </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-attributes>
 
         </java-type>
 
         </java-type>
Line 129: Line 128:
 
{|{{BMTableStyle}}
 
{|{{BMTableStyle}}
 
|-{{BMTHStyle}}
 
|-{{BMTHStyle}}
−
! Issue #  
+
! Issue#  
 
! Owner  
 
! Owner  
−
! Description / Notes
+
! Description/Notes
 
|-
 
|-
 
| 1
 
| 1
 
| D.McCann
 
| D.McCann
−
| Two possible ways to allow a path-based mapping to be configured are being considered:  <code>xml-attribute/xml-element</code> or <code>xml-element-wrapper</code>.  Which is preferred?  Design documentation for this support is located [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/PathBasedMappings#Decision_Point_1:__xml-attribute.2Fxml-element_vs._xml-element-wrapper here].
+
| Two possible ways to allow a path-based mapping to be configured are being considered:  <code>xml-attribute/xml-element</code> or <code>xml-element-wrapper</code>.  Which is preferred?  Design decisions for this support are located [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/PathBasedMappings#Decision_Point_1:__xml-attribute.2Fxml-element_vs._xml-element-wrapper here].
 
|-
 
|-
 
| 2
 
| 2
 
| D.McCann
 
| D.McCann
−
| Three possible ways to set the path for a mapping are being considered:  <code>name</code> overload vs. <code>xpath</code> vs. <code>name</code> + <code>grouping-element</code>.  Which is preferred?  Design documentation for this support is located [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/PathBasedMappings#Decision_Point_2:__name_overload_vs._xpath_vs._name_.2B_grouping-element here].
+
| Three possible ways to set the path for a mapping are being considered:  <code>name</code> overload vs. <code>xpath</code> vs. <code>name</code> + <code>grouping-element</code>.  Which is preferred?  Design decisions for this support are located [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/PathBasedMappings#Decision_Point_2:__name_overload_vs._xpath_vs._name_.2B_grouping-element here].
 +
|-
 +
| 3
 +
| D.McCann
 +
| What is the expected behavior when a namespace is set on an <code>xml-element-wrapper</code> that has a path set?
 
|}
 
|}
  
Line 148: Line 151:
 
{|{{BMTableStyle}}
 
{|{{BMTableStyle}}
 
|-{{BMTHStyle}}
 
|-{{BMTHStyle}}
−
! Issue #  
+
! Issue#  
−
! Description / Notes  
+
! Description/Notes  
 
! Decision
 
! Decision
 
|-
 
|-
−
|  
+
| 1
−
|  
+
| Two possible ways to allow a path-based mapping to be configured are being considered: <code>xml-attribute/xml-element</code> or <code>xml-element-wrapper</code>
−
|  
+
| <code>xml-element-wrapper</code> will be extended to handle multi-level paths, and enabled for use with <code>xml-attribute</code> and single-valued properties.
 +
|-
 +
| 2
 +
| Three possible ways to set the path for a mapping are being considered: <code>name</code> overload vs. <code>xpath</code> vs. <code>name</code> + <code>grouping-element</code>
 +
| <code>name</code> will be overloaded.
 
|}
 
|}
 +
 +
== 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 <code>name</code> attribute in a non-standard way are able to set a multi-level path.

Revision as of 07:31, 8 February 2010

XMLDirectMapping

Requirements

Provide support for XML direct mappings.

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

  • xml-attribute
  • xml-element


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

The following should be configurable:

  • Null policy
  • Get/set method names
  • Read only
  • Attribute classification
  • Default null value
  • CDATA
  • Converter

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">
    <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>

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 decisions for this support 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 decisions for this support are located here.
3 D.McCann What is the expected behavior when a namespace is set on an xml-element-wrapper that has a path set?

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.

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.
Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/DesignDocs/293925/MOXyExtensions/XMLDirectMapping&oldid=188920"

Back to the top