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"
(→XML Instance Document (read)) |
(→XML Instance Document (write)) |
||
Line 231: | Line 231: | ||
<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" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> | + | <ns0:employee id="66" xmlns:ns0="http://www.example.com/employees" xmlns:prj="http://www.example.com/projects" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> |
<projects> | <projects> | ||
<prj:project prj:managerId="99">XML External Metadata Support</prj:project> | <prj:project prj:managerId="99">XML External Metadata Support</prj:project> | ||
Line 250: | Line 250: | ||
<some-string xsi:nil="true" /> | <some-string xsi:nil="true" /> | ||
<a-string/> | <a-string/> | ||
− | </employee> | + | </ns0:employee> |
</source> | </source> | ||
Revision as of 11:08, 11 March 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:
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
via xml-path attribute. If xml-path is present, it is assumed to contain the entire XPath, hence the name and namespace attributes - if set - will be ignored, as well as any xml-element-wrapper declarations. 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 below and 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 below and 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 below and here. Note that CDATA cannot be applied to xml-attribute
.
Null Poilcy
Null policy will be supported via sub-element on xml-attribute
, xml-element
and xml-value
. The proposed schema modifications for the global null policy elements/complex types can be found here. An example of configuring a null policy on an XML direct mapping can be found below.
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 int projectId; public String firstName; public String lastName; public String projectName; public String data1; public String data2; public double salary; public String privateData; public String characterData; public String someString; public String aString; @javax.xml.bind.annotation.XmlTransient public boolean isSomeStringSet; String getProject() { return projectName; } void setProject(String name) { projectName = name; } String getSomeString() { return someString; } void setSomeString(String str) { someString = str; } public boolean isSetSomeString(Boolean ignoredParam) { return isSomeStringSet; } String getAString() { return aString; } void setAString(String str) { aString = str; } }
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/@prj: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-mapping xsi:type="xml-direct-mapping"> <attribute-name>characterData</attribute-name> <field name="character-data/text()" xsi:type="node"/> <is-cdata>true</is-cdata> </attribute-mapping> <attribute-mapping xsi:type="xml-direct-mapping"> <attribute-name>projectId</attribute-name> <field name="project-id/text()" xsi:type="node"/> <null-value xsi:type="xsd:int">-1</null-value> </attribute-mapping> <attribute-mapping xsi:type="xml-direct-mapping"> <attribute-name>someString</attribute-name> <get-method>getSomeString</get-method> <set-method>setSomeString</set-method> <field name="some-string/text()" xsi:type="node"/> <null-policy xsi:type="null-policy"> <null-representation-for-xml>EMPTY_NODE</null-representation-for-xml> </null-policy> </attribute-mapping> <attribute-mapping xsi:type="xml-direct-mapping"> <attribute-name>aString</attribute-name> <get-method>getAString</get-method> <set-method>setAString</set-method> <field name="a-string/text()" xsi:type="node"/> <null-policy xsi:type="null-policy"> <empty-node-represents-null>true</empty-node-represents-null> <null-representation-for-xml>ABSENT_NODE</null-representation-for-xml> </null-policy> </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 (read)
<?xml version="1.0" encoding="UTF-8"?> <ns0:employee id="66" salary="123456.78" xmlns:ns0="http://www.example.com/employees" xmlns:prj="http://www.example.com/projects" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <projects> <prj:project prj: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> <project-id/> <pieces-of-data> <data>data one</data> <data>data two</data> <data>data three</data> </pieces-of-data> <private-data>This is some private data</private-data> <character-data><![CDATA[<characters>a b c d e f g</characters>]]></character-data> <some-string /> </ns0:employee>
XML Instance Document (write)
<?xml version="1.0" encoding="UTF-8"?> <ns0:employee id="66" xmlns:ns0="http://www.example.com/employees" xmlns:prj="http://www.example.com/projects" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <projects> <prj:project prj:managerId="99">XML External Metadata Support</prj:project> </projects> <project-id>999</project-id> <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> <character-data><![CDATA[<characters>a b c d e f g</characters>]]></character-data> <some-string xsi:nil="true" /> <a-string/> </ns0: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" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <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-accessor-type="FIELD"> <xml-root-element name="employee" /> <java-attributes> <xml-attribute java-attribute="empId" xml-path="@id" /> <xml-attribute java-attribute="salary" read-only="true" /> <xml-attribute java-attribute="mgrId" xml-path="projects/prj:project/@prj:managerId" /> <xml-element java-attribute="firstName" xml-path="info/personal-info/first-name/text()" /> <xml-element java-attribute="lastName" xml-path="info/personal-info/last-name/text()" /> <xml-element java-attribute="data2" xml-path="pieces-of-data/data[2]/text()" /> <xml-element java-attribute="data1" xml-path="pieces-of-data/data[1]/text()" /> <xml-element java-attribute="privateData" name="private-data" write-only="true" /> <xml-element java-attribute="characterData" name="character-data" cdata="true" /> <xml-element java-attribute="projectId" name="project-id" default-value="-1" /> <xml-element java-attribute="projectName" xml-path="projects/prj:project/text()"> <xml-access-methods get-method="getProject" set-method="setProject" /> </xml-element> <xml-element java-attribute="someString" name="some-string"> <xml-access-methods get-method="getSomeString" set-method="setSomeString" /> <xml-is-set-null-policy xsi-nil-represents-null="true" empty-node-represents-null="false" null-representation-for-xml="XSI_NIL" is-set-method-name="isSetSomeString"> <is-set-parameter value="false" type="java.lang.Boolean" /> </xml-is-set-null-policy> </xml-element> <xml-element java-attribute="aString" name="a-string"> <xml-access-methods get-method="getAString" set-method="setAString" /> <xml-null-policy xsi-nil-represents-null="false" empty-node-represents-null="false" null-representation-for-xml="EMPTY_NODE" is-set-performed-for-absent-node="true" /> </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.