|
|
(18 intermediate revisions by the same user not shown) |
Line 8: |
Line 8: |
| === Decision Point 1: <code>xml-attribute</code>/<code>xml-element</code> vs. <code>xml-element-wrapper</code> === | | === Decision Point 1: <code>xml-attribute</code>/<code>xml-element</code> vs. <code>xml-element-wrapper</code> === |
| | | |
− | We are currently considering two possible options for supporting path-based mappings:
| + | There are three possible options for supporting path-based mappings: |
| * Utilize the <code>xml-attribute</code> and <code>xml-element</code> structures | | * Utilize the <code>xml-attribute</code> and <code>xml-element</code> structures |
− | ** Issue: if this apporach is taken, when is the expected behavior when an <code>xml-element-wrapper</code> is used with an <code>xml-element</code> that has the path set? | + | ** Issue: if this apporach is taken, what is the expected behavior when an <code>xml-element-wrapper</code> is used with an <code>xml-element</code> that has the path set? |
| * Utilize the <code>xml-element-wrapper</code> structure | | * Utilize the <code>xml-element-wrapper</code> structure |
| ** For this approach to work, we will have to enable use with single-valued properties and <code>xml-attribute</code> | | ** For this approach to work, we will have to enable use with single-valued properties and <code>xml-attribute</code> |
| | | |
− | === Decision Point 2: <code>name</code> overload vs. <code>xpath</code> vs. <code>name</code> + <code>grouping-element</code> ===
| + | The preferred approach is to utilize the <code>xml-attribute</code> and <code>xml-element</code> structures. |
| | | |
− | We are currently considering three possible methods of specifying the path for a given mapping: | + | === Decision Point 2: <code>name</code> overload vs. <code>xml-path</code> vs. <code>name</code> + <code>grouping-element</code> === |
| + | |
| + | We will need to consider three possible methods of specifying the path for a given mapping: |
| * Overload the <code>name</code> attribute | | * Overload the <code>name</code> attribute |
| ** This is the most simple approach, as no new attributes/elements need to be introduced. | | ** This is the most simple approach, as no new attributes/elements need to be introduced. |
− | ** Name can be used to set the path as follows: | + | ** <code>name</code> can be used to set the path as follows: |
− | *** <code><xml-attribute java-attribute="projectId" name="projects/project/id" /></code> | + | *** <code>name="projects/project/id"</code> |
− | * Add a new <code>xpath</code> attribute | + | ** Issue: this approach would require use of a standard mechanism in a non-standard way - is this acceptable? |
− | ** With this approach, the <code>xpath</code> would contain the entire path, i.e.: | + | * Add a new <code>xml-path</code> attribute |
− | *** <code><xml-attribute java-attribute="projectId" xpath="projects/project/id" /></code> | + | ** With this approach, the <code>xml-path</code> would contain the entire path, i.e.: |
− | **Issue: if both <code>name</code> and <code>xpath</code> are set, which takes precidence? | + | *** <code>xml-path="projects/project/id"</code> |
| + | **Issue: if both <code>name</code> and <code>xml-path</code> are set, which takes precedence? |
| * Combine <code>name</code> with a new <code>grouping-element</code> attribute | | * Combine <code>name</code> with a new <code>grouping-element</code> attribute |
− | ** With this approach a grouping element would be combined with the property name to get the entire path, i.e.: | + | ** With this approach a grouping element would be combined with the name to get the entire path, i.e.: |
− | *** <code><xml-attribute java-attribute="projectId" name="id" grouping-element="projects/project" /></code> | + | *** <code>name="id" grouping-element="projects/project"</code> |
− | | + | |
− | == Other Issues ==
| + | |
− | * Namespaces
| + | |
− | ** What is the expected behavior when a namespace is set with an XPath? For example, if we have <code><xml-element java-attribute="firstName" xml-path="myname/names/fname" namespace="www.example.com" /></code> to which element is the namespace applied, if any?
| + | |
− | | + | |
− | | + | |
− | | + | |
− | | + | |
− | * XPath Support
| + | |
− | ** There are a number of options:
| + | |
− | *** [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/XMLDirectMapping#XML_Metadata__Option_1:_overload_name_attribute_on_xml-element.2Fxml-attribute 1] overload <code>name</code> attribute on xml-element/xml-attribute
| + | |
− | *** [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/XMLDirectMapping#XML_Metadata__Option_2:_add_an_xml-path_attribute_to_xml-element.2Fxml-attribute 2] add an <code>xml-path</code> attribute to xml-element/xml-attribute
| + | |
− | *** [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/XMLDirectMapping#XML_Metadata__Option_3:_combine_name_and_xml-path_on_xml-element.2Fxml-attribute 3] combine <code>name</code> and <code>xml-path</code> on xml-element/xml-attribute
| + | |
− | *** enable use of xml-element-wrapper with non-collections and xml-attribute and one of:
| + | |
− | **** [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/XMLDirectMapping#XML_Metadata__Option_4:_overload_name_attribute_on_xml-element-wrapper 4] overload <code>name</code> attribute on xml-element-wrapper
| + | |
− | **** [http://wiki.eclipse.org/EclipseLink/DesignDocs/293925/XMLDirectMapping#XML_Metadata__Option_5:_add_an_xml-path_attribute_to_xml-element-wrapper 5] add an <code>xml-path</code> attribute to xml-element-wrapper for case where path is more than one level deep
| + | |
− | ** If overloading the <code>name</code> attribute is desirable, should we support <code>xml-path</code> as well such that users who prefer not to overload <code>name</code> have another option?
| + | |
− | ** If we choose to support both <code>name</code> and <code>xml-path</code>, which one takes precedence?
| + | |
− | ** Namespaces
| + | |
− | *** What is the expected behavior when a namespace is set with an XPath? For example, if we have <code><xml-element java-attribute="firstName" xml-path="myname/names/fname" namespace="www.example.com" /></code> to which element is the namespace applied, if any? Do we force the user to use a prefix on path elements individually, i.e. <code><xml-element java-attribute="firstName" xml-path="myname/ns0:names/fname" /></code>?
| + | |
− | | + | |
− | == Example: XPath Use With XMLDirectMapping ==
| + | |
− | | + | |
− | The following example will demonstrate how to configure an XMLDirectMapping using XPaths via XML Metadata:
| + | |
− | | + | |
− | === org.example.Employee.java ===
| + | |
− | | + | |
− | <source lang="java">
| + | |
− | package org.example;
| + | |
− | | + | |
− | public class Employee {
| + | |
− | public int empId;
| + | |
− | public int mgrId;
| + | |
− | public String firstName;
| + | |
− | public String lastName;
| + | |
− | public String projectName;
| + | |
− | }
| + | |
− | </source>
| + | |
− | | + | |
− | === Deployment XML ===
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | <class-mapping-descriptor xsi:type="xml-class-mapping-descriptor">
| + | |
− | <class>org.example.Employee</class>
| + | |
− | <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="name/first-name/text()" xsi:type="node"/>
| + | |
− | </attribute-mapping>
| + | |
− | <attribute-mapping xsi:type="xml-direct-mapping">
| + | |
− | <attribute-name>lasstName</attribute-name>
| + | |
− | <field name="name/last-name/text()" 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-mapping xsi:type="xml-direct-mapping">
| + | |
− | <attribute-name>mgrId</attribute-name>
| + | |
− | <field name="projects/prj:project/@managerId" 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>
| + | |
− | </source>
| + | |
− | | + | |
− | === XML Instance Document ===
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | <?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>
| + | |
− | </source>
| + | |
− | | + | |
− | === XML Metadata Option 1: overload <code>name</code> attribute on xml-element/xml-attribute ===
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | <?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-attribute java-attribute="mgrId" name="projects/prj:project/managerId" />
| + | |
− | <xml-element java-attribute="firstName" name="name/first-name" />
| + | |
− | <xml-element java-attribute="lastName" name="name/last-name" />
| + | |
− | <xml-element java-attribute="projectName" name="projects/prj:project" />
| + | |
− | </java-attributes>
| + | |
− | </java-type>
| + | |
− | </java-types>
| + | |
− | </xml-bindings>
| + | |
− | </source>
| + | |
− | | + | |
− | === XML Metadata Option 2: add an <code>xml-path</code> attribute to xml-element/xml-attribute ===
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | <?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-attribute java-attribute="mgrId" xml-path="projects/prj:project/managerId" />
| + | |
− | <xml-element java-attribute="firstName" xml-path="name/first-name" />
| + | |
− | <xml-element java-attribute="lastName" xml-path="name/last-name" />
| + | |
− | <xml-element java-attribute="projectName" xml-path="projects/prj:project" />
| + | |
− | </java-attributes>
| + | |
− | </java-type>
| + | |
− | </java-types>
| + | |
− | </xml-bindings>
| + | |
− | </source>
| + | |
− | | + | |
− | === XML Metadata Option 3: combine <code>name</code> and <code>xml-path</code> on xml-element/xml-attribute ===
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | <?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-attribute java-attribute="mgrId" name="managerId" xml-path="projects/prj:project" />
| + | |
− | <xml-element java-attribute="firstName" name="first-name" xml-path="name" />
| + | |
− | <xml-element java-attribute="lastName" name="last-name" xml-path="name" />
| + | |
− | <xml-element java-attribute="projectName" name="prj:project" xml-path="projects" />
| + | |
− | </java-attributes>
| + | |
− | </java-type>
| + | |
− | </java-types>
| + | |
− | </xml-bindings>
| + | |
− | </source>
| + | |
| | | |
− | === XML Metadata Option 4: overload <code>name</code> attribute on xml-element-wrapper ===
| + | The preferred approach would be to Add a new <code>xml-path</code> attribute |
| | | |
− | <source lang="xml">
| + | === Decision Point 3: Optional Element Usage === |
− | <?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-attribute java-attribute="mgrId" name="managerId">
| + | |
− | <xml-element-wrapper name="projects/prj:project" />
| + | |
− | </xml-attribute>
| + | |
− | <xml-element java-attribute="firstName" name="first-name">
| + | |
− | <xml-element-wrapper name="name" />
| + | |
− | </xml-element>
| + | |
− | <xml-element java-attribute="lastName" name="last-name">
| + | |
− | <xml-element-wrapper name="name" />
| + | |
− | </xml-element>
| + | |
− | <xml-element java-attribute="projectName" name="project" namespace="http://www.example.com/projects">
| + | |
− | <xml-element-wrapper name="projects" />
| + | |
− | </xml-attribute>
| + | |
− | </java-attributes>
| + | |
− | </java-type>
| + | |
− | </java-types>
| + | |
− | </xml-bindings>
| + | |
− | </source>
| + | |
| | | |
− | === XML Metadata Option 5: add an <code>xml-path</code> attribute to xml-element-wrapper ===
| + | If use of <code>xml-element-wrapper</code> is chosen in Decision Point 1 above, what will the expected behavior be when <code>namespace</code>, <code>nillable</code>, and/or <code>required</code> is set in addition to an XPath? |
| | | |
− | <source lang="xml"> | + | Regarding <code>namespace</code>, the preferred approach is to apply the namespace to any path element that isn't already prefixed. |
− | <?xml version="1.0" encoding="US-ASCII"?>
| + | Regarding <code>nillable</code>, and/or <code>required</code>, the preferred approach is to apply these to the last path element. |
− | <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-attribute java-attribute="mgrId" name="managerId">
| + | |
− | <!-- use xml-path if more than 1 level deep -->
| + | |
− | <xml-element-wrapper xml-path="projects/prj:project" />
| + | |
− | </xml-attribute>
| + | |
− | <xml-element java-attribute="firstName" name="first-name">
| + | |
− | <xml-element-wrapper name="name" />
| + | |
− | </xml-element>
| + | |
− | <xml-element java-attribute="lastName" name="last-name">
| + | |
− | <xml-element-wrapper name="name" />
| + | |
− | </xml-element>
| + | |
− | <xml-element java-attribute="projectName" name="project" namespace="http://www.example.com/projects">
| + | |
− | <xml-element-wrapper name="projects" />
| + | |
− | </xml-attribute>
| + | |
− | </java-attributes>
| + | |
− | </java-type>
| + | |
− | </java-types>
| + | |
− | </xml-bindings>
| + | |
− | </source>
| + | |
Provide support for path-based mappings.
We will need to consider three possible methods of specifying the path for a given mapping: