Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be 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/UserGuide/MOXy/Simple Values/Single Values/XMLDirectMapping"

m (Replacing page with 'Please see http://www.eclipse.org/eclipselink/documentation/2.4/moxy/simple_values001.htm')
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
{{EclipseLink_UserGuide
+
Please see http://www.eclipse.org/eclipselink/documentation/2.4/moxy/simple_values001.htm
−
|eclipselink=y
+
−
|eclipselinktype=MOXy
+
−
|info=y
+
−
|api=y
+
−
|apis= * [http://www.eclipse.org/eclipselink/api/latest/javax/xml/bind/annotation/XmlAttribute.html XmlAttribute]
+
−
* [http://www.eclipse.org/eclipselink/api/latest/javax/xml/bind/annotation/XmlElement.html XmlElement]
+
−
* [http://www.eclipse.org/eclipselink/api/latest/javax/xml/bind/annotation/XmlValue.html XmlValue]
+
−
|toc=y
+
−
}}
+
−
 
+
−
=Mapping Simple Values=
+
−
This section demonstrates several ways to map simple Java values directly to XML text nodes.
+
−
 
+
−
Given the XML schema in this example, the figure below illustrates an XML direct mapping to an attribute in a corresponding XML document.
+
−
 
+
−
<source lang="xml">
+
−
<?xml version="1.0" encoding="UTF-8"?>
+
−
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
−
 
+
−
  <xsd:element name="customer" type="customer-type"/>
+
−
 
+
−
  <xsd:complexType name="customer-type">
+
−
      <xsd:attribute name="id" type="xsd:integer"/>
+
−
  </xsd:complexType>
+
−
 
+
−
</xsd:schema>
+
−
</source>
+
−
 
+
−
[[Image:dxmatt.gif]]<br><br>
+
−
 
+
−
==Mapping to an Attribute==
+
−
 
+
−
The following example shows how to annotate your Java class to obtain this mapping with EclipseLink.  All that is needed is the standard JAXB <tt>@XmlAttribute</tt> annotation.
+
−
 
+
−
<source lang="java">
+
−
@XmlRootElement
+
−
@XmlAccessorType(XmlAccessType.FIELD)
+
−
public class Customer {
+
−
  @XmlAttribute
+
−
  private Integer id;
+
−
 
+
−
  ...
+
−
}
+
−
</source>
+
−
 
+
−
The example below shows how to to define your mapping information in EclipseLink's OXM metadata format.
+
−
 
+
−
<source lang="xml">
+
−
...
+
−
<java-type name="Customer">
+
−
  <xml-root-element name="customer"/>
+
−
  <java-attributes>
+
−
      <xml-attribute java-attribute="id"/>
+
−
  </java-attributes>
+
−
</java-type>
+
−
...
+
−
</source>
+
−
 
+
−
<br><br>
+
−
 
+
−
==Mapping to a Text Node==
+
−
This section describes using an XML direct mapping when doing the following:
+
−
* [[#Mapping to a Text Node in a Simple Sequence|Mapping to a Text Node in a Simple Sequence]]
+
−
* [[#Mapping to a Text Node in a Subelement|Mapping to a Text Node in a Subelement]]
+
−
* [[#Mapping to a Text Node by Position|Mapping to a Text Node by Position]]
+
−
* [[#Mapping to a Simple Text Node|Mapping to a Simple Text Node]]
+
−
 
+
−
 
+
−
===Mapping to a Text Node in a Simple Sequence===
+
−
Given the XML schema in this example, the figure below illustrates an XML direct mapping to individual text nodes in a sequence in a corresponding XML document.
+
−
 
+
−
<source lang="xml">
+
−
<?xml version="1.0" encoding="UTF-8"?>
+
−
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
−
 
+
−
  <xsd:element name="customer" type="customer-type"/>
+
−
 
+
−
  <xsd:complexType name="customer-type">
+
−
      <xsd:sequence>
+
−
        <xsd:element name="first-name" type="xsd:string"/>
+
−
        <xsd:element name="last-name" type="xsd:string"/>
+
−
      </xsd:sequence>
+
−
  </xsd:complexType>
+
−
 
+
−
</xsd:schema>
+
−
</source>
+
−
 
+
−
[[Image:dxmss.gif]]<br><br>
+
−
 
+
−
The following example shows how to annotate your Java class to obtain this mapping with EclipseLink. Here, the standard JAXB <tt>@XmlElement</tt> annotation is used, with a customized element name.
+
−
 
+
−
<source lang="java">
+
−
@XmlRootElement
+
−
@XmlAccessorType(XmlAccessType.FIELD)
+
−
public class Customer {
+
−
  @XmlElement(name="first-name")
+
−
  private String firstName;
+
−
 
+
−
  @XmlElement(name="last-name")
+
−
  private String lastName;
+
−
 
+
−
  ...
+
−
}
+
−
</source>
+
−
 
+
−
{{tip||In this example, we have explicitly specified the XML element names for the mapped attributes.  This is an optional configuration - without an explicit name set, the XML element will simply match the Java attribute name (i.e. we would see <tt><firstName>Jane</firstName></tt> in XML).  For more information on JAXB name-binding algorithms, see "Appendix D: Binding XML Names to Java Identifiers" of the ''Java Architecture for XML Binding (JAXB) 2.2 Specification''.}}
+
−
 
+
−
 
+
−
The example below shows how to to define your mapping information in EclipseLink's OXM metadata format.  To specify a custom element name, the <tt>name</tt> attribute is used.
+
−
 
+
−
<source lang="xml">
+
−
...
+
−
<java-type name="Customer">
+
−
  <xml-root-element name="customer"/>
+
−
  <java-attributes>
+
−
      <xml-element java-attribute="firstName" name="first-name"/>
+
−
      <xml-element java-attribute="lastName" name="last-name"/>
+
−
  </java-attributes>
+
−
</java-type>
+
−
...
+
−
</source>
+
−
 
+
−
<br><br>
+
−
 
+
−
===Mapping to a Text Node in a Sub-element===
+
−
Given the XML schema in this example, the following figure illustrates an XML direct mapping to a text node in a subelement in a corresponding XML document.
+
−
 
+
−
<source lang="xml">
+
−
<?xml version="1.0" encoding="UTF-8"?>
+
−
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
−
 
+
−
  <xsd:element name="customer" type="customer-type"/>
+
−
 
+
−
  <xsd:complexType name="customer-type">
+
−
      <xsd:sequence>
+
−
        <xsd:element name="personal-info">
+
−
            <xsd:complexType>
+
−
              <xsd:sequence>
+
−
                  <xsd:element name="first-name" type="xsd:string"/>
+
−
                  <xsd:element name="last-name" type="xsd:string"/>
+
−
              <xsd:sequence>
+
−
            </xsd:complexType>
+
−
        </xsd:element>
+
−
      </xsd:sequence>
+
−
  </xsd:complexType>
+
−
 
+
−
</xsd:schema>
+
−
</source>
+
−
 
+
−
[[Image:dxmse.gif]]<br><br>
+
−
 
+
−
The following example shows how to annotate your Java class to obtain this mapping with EclipseLink. Here, because we are going beyond a simple element name customization and are actually introducing new XML structure, EclipseLink's <tt>@XmlPath</tt> annotation is used.
+
−
 
+
−
<source lang="java">
+
−
@XmlRootElement
+
−
@XmlAccessorType(XmlAccessType.FIELD)
+
−
public class Customer {
+
−
  @XmlPath("personal-info/first-name/text()")
+
−
  private String firstName;
+
−
 
+
−
  @XmlPath("personal-info/last-name/text()")
+
−
  private String lastName;
+
−
 
+
−
  ...
+
−
}
+
−
</source>
+
−
 
+
−
The example below shows how to to define your mapping information in EclipseLink's OXM metadata format.  Here, the customized XML path is defined in the <tt>xml-path</tt> attribute.
+
−
 
+
−
<source lang="xml">
+
−
...
+
−
<java-type name="Customer">
+
−
  <xml-root-element name="customer"/>
+
−
  <java-attributes>
+
−
      <xml-element java-attribute="firstName" xml-path="personal-info/first-name/text()"/>
+
−
      <xml-element java-attribute="lastName" xml-path="personal-info/last-name/text()"/>
+
−
  </java-attributes>
+
−
</java-type>
+
−
...
+
−
</source>
+
−
 
+
−
<br><br>
+
−
 
+
−
===Mapping to a Text Node by Position===
+
−
Given the XML schema in this example, the following figure illustrates an XML direct mapping to a text node by position in a corresponding XML document.
+
−
 
+
−
<source lang="xml">
+
−
<?xml version="1.0" encoding="UTF-8"?>
+
−
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
−
 
+
−
  <xsd:element name="customer" type="customer-type"/>
+
−
 
+
−
  <xsd:complexType name="customer-type">
+
−
      <xsd:sequence>
+
−
        <xsd:element name="name" type="xsd:string" maxOccurs="2"/>
+
−
      </xsd:sequence>
+
−
  </xsd:complexType>
+
−
 
+
−
</xsd:schema>
+
−
</source>
+
−
 
+
−
[[Image:dxmpos.gif]]<br><br>
+
−
 
+
−
The example below shows how to configure this mapping in Java.  Again, for more complex XML path customization, EclipseLink's <tt>@XmlPath</tt> annotation is used.
+
−
 
+
−
<source lang="java">
+
−
@XmlRootElement
+
−
@XmlAccessorType(XmlAccessType.FIELD)
+
−
public class Customer {
+
−
  @XmlPath("name[1]/text()")
+
−
  private String firstName;
+
−
 
+
−
  @XmlPath("name[2]/text()")
+
−
  private String lastName;
+
−
 
+
−
  ...
+
−
}
+
−
</source>
+
−
 
+
−
The following example shows how to to define your mapping information in EclipseLink's OXM metadata format.
+
−
 
+
−
<source lang="xml">
+
−
...
+
−
<java-type name="Customer">
+
−
  <xml-root-element name="customer"/>
+
−
  <java-attributes>
+
−
      <xml-element java-attribute="firstName" xml-path="name[1]/text()"/>
+
−
      <xml-element java-attribute="lastName" xml-path="name[2]/text()"/>
+
−
  </java-attributes>
+
−
</java-type>
+
−
...
+
−
</source>
+
−
 
+
−
<br><br>
+
−
 
+
−
===Mapping to a Simple Text Node===
+
−
Given the XML schema in this example, the following figure illustrates an XML direct mapping to a simple text node in a corresponding XML document.
+
−
 
+
−
<source lang="xml">
+
−
<?xml version="1.0" encoding="UTF-8"?>
+
−
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
−
 
+
−
  <xsd:element name="phone-number" type="xsd:string"/>
+
−
 
+
−
</xsd:schema>
+
−
</source>
+
−
 
+
−
[[Image:dxmstn.gif]]<br><br>
+
−
 
+
−
The following example shows how to annotate your Java class to obtain this mapping with EclipseLink. In this case, the <tt>@XmlValue</tt> annotation will be used.
+
−
 
+
−
<source lang="java">
+
−
@XmlRootElement(name="phone-number")
+
−
@XmlAccessorType(XmlAccessType.FIELD)
+
−
public class PhoneNumber {
+
−
  @XmlValue
+
−
  private String number;
+
−
 
+
−
  ...
+
−
}
+
−
</source>
+
−
 
+
−
The example below shows how to to define your mapping information in EclipseLink's OXM metadata format.
+
−
 
+
−
<source lang="xml">
+
−
...
+
−
<java-type name="PhoneNumber">
+
−
  <xml-root-element name="phone-number"/>
+
−
  <java-attributes>
+
−
      <xml-value java-attribute="number"/>
+
−
  </java-attributes>
+
−
</java-type>
+
−
...
+
−
</source>
+
−
 
+
−
<br><br>
+
−
 
+
−
==Mapping to a Specified Schema Type==
+
−
In most cases, EclipseLink can determine the target format in the XML document. However, there are cases where you must specify which one of a number of possible targets EclipseLink should use. For example, a <tt>java.util.Calendar</tt> could be marshalled to a schema <tt>date</tt>, <tt>time</tt>, or <tt>dateTime</tt> node, or a <tt>byte[]</tt> could be marshalled to a schema <tt>hexBinary</tt> or <tt>base64Binary</tt> node.
+
−
 
+
−
The following XML schema and figure illustrate an XML direct mapping from a <tt>Calendar</tt> object in Java to a <tt>date</tt> field in XML.
+
−
 
+
−
<source lang="xml">
+
−
<?xml version="1.0" encoding="UTF-8"?>
+
−
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
−
 
+
−
  <xsd:element name="customer" type="customer-type"/>
+
−
 
+
−
  <xsd:complexType name="customer-type">
+
−
      <xsd:sequence>
+
−
        <xsd:element name="hire-date" type="xsd:date"/>
+
−
      </xsd:sequence>
+
−
  </xsd:complexType>
+
−
 
+
−
</xsd:schema>
+
−
</source>
+
−
 
+
−
[[Image:Schematypedate.png]]
+
−
 
+
−
The example below shows how to annotate your Java class to obtain this mapping with EclipseLink.  Here, the <tt>@XmlSchemaType</tt> is used to specify the datatype that will appear in the marshalled XML.
+
−
 
+
−
<source lang="java">
+
−
@XmlRootElement
+
−
@XmlAccessorType(XmlAccessType.FIELD)
+
−
public class Customer {
+
−
  @XmlElement(name="hire-date")
+
−
  @XmlSchemaType(name="date")
+
−
  private Calendar hireDate;
+
−
 
+
−
  ...
+
−
}
+
−
</source>
+
−
 
+
−
The following example shows how to to define your mapping information in EclipseLink's OXM metadata format.
+
−
 
+
−
<source lang="xml">
+
−
...
+
−
<java-type name="Customer">
+
−
  <xml-root-element name="customer"/>
+
−
  <java-attributes>
+
−
      <xml-element java-attribute="hireDate" name="hire-date">
+
−
        <xml-schema-type name="date"/>
+
−
      </xml-element>
+
−
  </java-attributes>
+
−
</java-type>
+
−
...
+
−
</source>
+
−
 
+
−
<br><br>
+
−
 
+
−
===Using Java Type Adapters===
+
−
The next example schema and figure illustrate XML direct mappings to two different text nodes of different binary types.
+
−
 
+
−
<source lang="xml">
+
−
<?xml version="1.0" encoding="UTF-8"?>
+
−
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
−
 
+
−
  <xsd:element name="customer" type="customer-type"/>
+
−
 
+
−
  <xsd:complexType name="customer-type">
+
−
      <xsd:sequence>
+
−
        <xsd:element name="resume" type="xsd:base64Binary"/>
+
−
        <xsd:element name="picture" type="xsd:hexBinary"/>
+
−
      </xsd:sequence>
+
−
  </xsd:complexType>
+
−
 
+
−
</xsd:schema>
+
−
</source>
+
−
 
+
−
[[Image:dxmscht.gif]]<br><br>
+
−
 
+
−
The example below shows how to annotate your Java class to obtain this mapping with EclipseLink.  By default, JAXB will marshall <tt>byte[]</tt> to <tt>base64Binary</tt>, so nothing special is needed for the <tt>resume</tt> mapping.  To map to a <tt>hexBinary</tt> field, the <tt>@XmlSchemaType</tt> annotation specifies the XML type, while <tt>@XmlJavaTypeAdapter</tt> specifies the adapter class that will be responsible for converting the value (in this case, the built-in JAXB <tt>HexBinaryAdapter</tt>).
+
−
 
+
−
<source lang="java">
+
−
@XmlRootElement
+
−
@XmlAccessorType(XmlAccessType.FIELD)
+
−
public class Customer {
+
−
  private byte[] resume;
+
−
 
+
−
  @XmlSchemaType(name="hexBinary")
+
−
  @XmlJavaTypeAdapter(HexBinaryAdapter.class)
+
−
  private byte[] picture;
+
−
 
+
−
  ...
+
−
}
+
−
</source>
+
−
 
+
−
The following example shows how to to define your mapping information in EclipseLink's OXM metadata format.
+
−
 
+
−
<source lang="xml">
+
−
...
+
−
<java-type name="Customer">
+
−
  <xml-root-element name="customer"/>
+
−
  <java-attributes>
+
−
      <xml-element java-attribute="resume"/>
+
−
      <xml-element java-attribute="picture">
+
−
        <xml-schema-type name="hexBinary"/>
+
−
        <xml-java-type-adapter value="javax.xml.bind.annotation.adapters.HexBinaryAdapter"/>
+
−
      </xml-element>
+
−
  </java-attributes>
+
−
</java-type>
+
−
...
+
−
</source>
+
−
 
+
−
<br><br>
+
−
 
+
−
==Mapping with a Simple Type Translator==
+
−
If the type of a node is not defined in your XML schema, you can configure an XML direct mapping to use the <tt>xsi:type</tt> attribute to provide type information.
+
−
 
+
−
Given the XML schema in this example, the figure below illustrates a Java class that can be mapped to a corresponding XML document.
+
−
 
+
−
<source lang="xml">
+
−
<?xml version="1.0" encoding="UTF-8"?>
+
−
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
−
+
−
  <xsd:element name="phone-number" type="phone-number-type"/>
+
−
+
−
  <xsd:complexType name="phone-number-type">
+
−
      <xsd:sequence>
+
−
        <xsd:element name="area-code" type="anySimpleType"/>
+
−
        <xsd:element name="number" type="anySimpleType"/>
+
−
      </xsd:sequence>
+
−
  </xsd:complexType>
+
−
+
−
</xsd:schema>
+
−
</source>
+
−
 
+
−
[[Image:dxmsttc.gif]]<br><br>
+
−
 
+
−
The following figure illustrates an XML direct mapping with a simple type translator in an XML document that conforms to the schema above.
+
−
 
+
−
[[Image:dxmsttm.gif]]<br><br>
+
−
 
+
−
The following example shows shows how to annotate your Java class to obtain this mapping with EclipseLink.
+
−
 
+
−
<source lang="java">
+
−
@XmlRootElement(name="phone-number")
+
−
public class PhoneNumber {
+
−
  @XmlElement(name="area-code")
+
−
  private Object areaCode;
+
−
 
+
−
  private Object number;
+
−
 
+
−
  ...
+
−
}
+
−
</source>
+
−
 
+
−
The example below shows how to define your mapping information in EclipseLink's OXM metadata format.
+
−
 
+
−
<source lang="xml">
+
−
...
+
−
<java-type name="PhoneNumber">
+
−
  <xml-root-element name="phone-number"/>
+
−
  <java-attributes>
+
−
      <xml-element java-attribute="areaCode" name="area-code"/>
+
−
      <xml-element java-attribute="number"/>
+
−
  </java-attributes>
+
−
</java-type>
+
−
...
+
−
</source>
+
−
 
+
−
For more information, see [[Introduction%20to%20Mappings%20(ELUG)#Simple Type Translator|Simple Type Translator]].
+
−
 
+
−
{{EclipseLink_MOXy
+
−
|previous= [[EclipseLink/UserGuide/MOXy/Simple_Values|Simple Values]]
+
−
|next=    [[EclipseLink/UserGuide/MOXy/Simple_Values/Collections/XMLDirectCollectionMapping|Mapping Collections]]
+
−
|up=      [[EclipseLink/UserGuide/MOXy/Simple_Values|Simple Values]]
+
−
|version=2.2.0
+
−
}}
+

Latest revision as of 10:17, 8 November 2012

Please see http://www.eclipse.org/eclipselink/documentation/2.4/moxy/simple_values001.htm

Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/UserGuide/MOXy/Simple_Values/Single_Values/XMLDirectMapping&oldid=321300"

This page was last modified 10:17, 8 November 2012 by Rick Sapir. Based on work by Rick Barkhouse.

Back to the top