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.
Difference between revisions of "EclipseLink/DesignDocs/293925/MOXyExtensions/XMLDirectMapping"
(→Null value) |
(→Design) |
||
Line 55: | Line 55: | ||
<xml-element-wrapper name="addresses/address[2]" /> | <xml-element-wrapper name="addresses/address[2]" /> | ||
</xml-element> | </xml-element> | ||
+ | </source> | ||
+ | |||
+ | ==== Positional Mappings ==== | ||
+ | Positional mappings will be supported on <code>xml-element</code> and <code>xml-value</code> by overloading <code>name</code>. For example, the following would be used to create a mapping to the second occurrence of <code>name</code>: | ||
+ | <source lang="xml"> | ||
+ | <xml-element java-attribute="name" name="name[2]" /> | ||
</source> | </source> | ||
Revision as of 11:26, 11 February 2010
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
- Null value
- CDATA (boolean)
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
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>
and xml-value
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>
Positional Mappings
Positional mappings will be supported on xml-element
and xml-value
by overloading name
. For example, the following would be used to create a mapping to the second occurrence of name
:
<xml-element java-attribute="name" name="name[2]" />
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
, xml-element
and xml-value
, i.e.:
<xml-attribute java-attribute="salary" read-only="true" />
Write only
Write only will be supported via boolean attribute on xml-attribute
, xml-element
and xml-value
, i.e.:
<xml-attribute java-attribute="privateData" write-only="true" />
CDATA
CDATA will be supported via boolean attribute on xml-element
and xml-value
, i.e.:
<xml-element java-attribute="characterData" cdata="true" />
Note that CDATA is not supported on attributes.
Converters
Converters will be supported by extending our existing xml-adapter
functionality.
Null value
The default null value will be supported as a sub-element on xml-attribute
, xml-element
and xml-value
. The schema structure of this element will be as follows:
<xsd:element name="null-value" type="xsd:anySimpleType" minOccurs="0" />
An example of setting the null value in XML metadata would be:
<xml-element java-attribute="empId" name="id"> <null-value xsi:type="xs:int">-1</null-value> </xml-element>
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.
|
6 | How can we support positional mappings? | Positional mappings will be supported by overloading the name attribute on xml-element .
|
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.