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
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.
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="first-name/text()" xsi:type="node"/> </attribute-mapping> <attribute-mapping xsi:type="xml-direct-mapping"> <attribute-name>lastName</attribute-name> <field name="last-name/text()" xsi:type="node"/> </attribute-mapping> <attribute-mapping xsi:type="xml-direct-mapping"> <attribute-name>projectName</attribute-name> <field name="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"> <first-name>Joe</first-name> <last-name>Black</last-name> <prj:project>XML External Metadata Support</prj:project> </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 java-attribute="lastName" name="last-name" /> <xml-element java-attribute="projectName" name="prj:project" /> </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.
|
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; it will be 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 a
grouping-element
attribute such that users who do not wish use thename
attribute in a non-standard way are able to set the XPath.