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

< EclipseLink‎ | UserGuide‎ | MOXy‎ | Simple Values

Revision as of 11:02, 5 July 2011

EclipseLink MOXy

EclipseLink
Website
Download
Community
Mailing List • Forums • IRC • mattermost
Issues
Open • Help Wanted • Bug Day
Contribute
Browse Source

Key API

1 Mapping Simple Values

Mapping Simple Values

This section demonstrates several ways to map simple Java values directly to XML text nodes.

Mapping to an Attribute

Given the XML schema in this example, the figure below illustrates an XML direct mapping to an attribute in a corresponding XML document.

<?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>

The following example shows how to annotate your Java class to obtain this mapping with EclipseLink. All that is needed is the standard JAXB @XmlAttribute annotation.

package example;
 
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
   @XmlAttribute
   private Integer id;
 
   ...
}

The example below shows how to to define your mapping information in EclipseLink's OXM metadata format.

...
<java-type name="Customer">
   <xml-root-element name="customer"/>
   <java-attributes>
      <xml-attribute java-attribute="id"/>
   </java-attributes>
</java-type>
...

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 Subelement
Mapping to a Text Node by Position
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.

<?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>

The following example shows how to annotate your Java class to obtain this mapping with EclipseLink. Here, the standard JAXB @XmlElement annotation is used, with a customized element name.

package example;
 
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
   @XmlElement(name="first-name")
   private String firstName;
 
   @XmlElement(name="last-name")
   private String lastName;
 
   ...
}

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 <firstName>Jane</firstName> 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 name attribute is used.

...
<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>
...

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.

<?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>

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 @XmlPath annotation is used.

package example;
 
import javax.xml.bind.annotation.*;
import org.eclipse.persistence.oxm.annotations.*;
 
@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;
 
   ...
}

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 xml-path attribute.

...
<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>
...

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.

<?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>

The example below shows how to configure this mapping in Java. Again, for more complex XML path customization, EclipseLink's @XmlPath annotation is used.

package example;
 
import javax.xml.bind.annotation.*;
import org.eclipse.persistence.oxm.annotations.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
   @XmlPath("name[1]/text()")
   private String firstName;
 
   @XmlPath("name[2]/text()")
   private String lastName;
 
   ...
}

The following example shows how to to define your mapping information in EclipseLink's OXM metadata format.

...
<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>
...

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.

<?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>

The following example shows how to annotate your Java class to obtain this mapping with EclipseLink. In this case, the @XmlValue annotation will be used.

package example;
 
import javax.xml.bind.annotation.*;
 
@XmlRootElement(name="phone-number")
@XmlAccessorType(XmlAccessType.FIELD)
public class PhoneNumber {
   @XmlValue
   private String number;
 
   ...
}

The example below shows how to to define your mapping information in EclipseLink's OXM metadata format.

...
<java-type name="PhoneNumber">
   <xml-root-element name="phone-number"/>
   <java-attributes>
      <xml-value java-attribute="number"/>
   </java-attributes>
</java-type>
...

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 java.util.Calendar could be marshalled to a schema date, time, or dateTime node, or a byte[] could be marshalled to a schema hexBinary or base64Binary node.

The following XML schema and figure illustrate an XML direct mapping from a Calendar object in Java to a date field in 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>

The example below shows how to annotate your Java class to obtain this mapping with EclipseLink. Here, the @XmlSchemaType is used to specify the datatype that will appear in the marshalled XML.

package example;
 
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
   @XmlElement(name="hire-date")
   @XmlSchemaType(name="date")
   private Calendar hireDate;
 
   ...
}

The following example shows how to to define your mapping information in EclipseLink's OXM metadata format.

...
<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>
...

Using Java Type Adapters

The next example schema and figure illustrate XML direct mappings to two different text nodes of different binary types.

<?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>

The example below shows how to annotate your Java class to obtain this mapping with EclipseLink. By default, JAXB will marshall byte[] to base64Binary, so nothing special is needed for the resume mapping. To map to a hexBinary field, the @XmlSchemaType annotation specifies the XML type, while @XmlJavaTypeAdapter specifies the adapter class that will be responsible for converting the value (in this case, the built-in JAXB HexBinaryAdapter).

package example;
 
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
   private byte[] resume;
 
   @XmlSchemaType(name="hexBinary")
   @XmlJavaTypeAdapter(HexBinaryAdapter.class)
   private byte[] picture;
 
   ...
}

The following example shows how to to define your mapping information in EclipseLink's OXM metadata format.

...
<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>
...

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 xsi:type 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.

<?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>

The following figure illustrates an XML direct mapping with a simple type translator in an XML document that conforms to the schema above.

The following example shows shows how to annotate your Java class to obtain this mapping with EclipseLink.

package example;
 
import javax.xml.bind.annotation.*;
 
@XmlRootElement(name="phone-number")
public class PhoneNumber {
   @XmlElement(name="area-code")
   private Object areaCode;
 
   private Object number;
 
   ...
}

The example below shows how to define your mapping information in EclipseLink's OXM metadata format.

...
<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>
...

For more information, see Simple Type Translator.

Version: DRAFT
Other versions...

Handling Inheritance		Mapping Collections of Simple Values
EclipseLink Home MOXy User Guide: Table of Contents, Search
How to contribute to this guide...

Category:

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

@@ Line 16: / Line 16: @@
 Given the XML schema in this example, the figure below illustrates an XML direct mapping to an attribute in a corresponding XML document.
+<div style="width:700px">
 <source lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
@@ Line 28: / Line 29: @@
 </xsd:schema>
 </source>
+</div>
 [[Image:dxmatt.gif]]<br><br>
@@ Line 33: / Line 35: @@
 The following example shows how to annotate your Java class to obtain this mapping with EclipseLink.  All that is needed is the standard JAXB '''@XmlAttribute''' annotation.
+<div style="width:700px">
 <source lang="java">
 package example;
@@ Line 47: / Line 50: @@
 }
 </source>
+</div>
 The example below shows how to to define your mapping information in EclipseLink's OXM metadata format.
+<div style="width:700px">
 <source lang="xml">
 ...
@@ Line 60: / Line 65: @@
 ...
 </source>
+</div>
 <br><br>
@@ Line 75: / Line 81: @@
 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.
+<div style="width:700px">
 <source lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
@@ Line 90: / Line 97: @@
 </xsd:schema>
 </source>
+</div>
 [[Image:dxmss.gif]]<br><br>
@@ Line 95: / Line 103: @@
 The following example shows how to annotate your Java class to obtain this mapping with EclipseLink. Here, the standard JAXB '''@XmlElement''' annotation is used, with a customized element name.
+<div style="width:700px">
 <source lang="java">
 package example;
@@ Line 112: / Line 121: @@
 }
 </source>
+</div>
 {{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 '''<firstName>Jane</firstName>''' 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''.}}
@@ Line 118: / Line 128: @@
 The example below shows how to to define your mapping information in EclipseLink's OXM metadata format.  To specify a custom element name, the '''name''' attribute is used.
+<div style="width:700px">
 <source lang="xml">
 ...
@@ Line 129: / Line 140: @@
 ...
 </source>
+</div>
 <br><br>
@@ Line 136: / Line 148: @@
 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.
+<div style="width:700px">
 <source lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
@@ Line 157: / Line 170: @@
 </xsd:schema>
 </source>
+</div>
 [[Image:dxmse.gif]]<br><br>
@@ Line 162: / Line 176: @@
 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 '''@XmlPath''' annotation is used.
+<div style="width:700px">
 <source lang="java">
 package example;
@@ Line 180: / Line 195: @@
 }
 </source>
+</div>
 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 '''xml-path''' attribute.
+<div style="width:700px">
 <source lang="xml">
 ...
@@ Line 194: / Line 211: @@
 ...
 </source>
+</div>
 <br><br>
@@ Line 200: / Line 218: @@
 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.
+<div style="width:700px">
 <source lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
@@ Line 214: / Line 233: @@
 </xsd:schema>
 </source>
+</div>
 [[Image:dxmpos.gif]]<br><br>
@@ Line 219: / Line 239: @@
 The example below shows how to configure this mapping in Java.  Again, for more complex XML path customization, EclipseLink's '''@XmlPath''' annotation is used.
+<div style="width:700px">
 <source lang="java">
 package example;
@@ Line 237: / Line 258: @@
 }
 </source>
+</div>
 The following example shows how to to define your mapping information in EclipseLink's OXM metadata format.
+<div style="width:700px">
 <source lang="xml">
 ...
@@ Line 251: / Line 274: @@
 ...
 </source>
+</div>
 <br><br>
@@ Line 257: / Line 281: @@
 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.
+<div style="width:700px">
 <source lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
@@ Line 265: / Line 290: @@
 </xsd:schema>
 </source>
+</div>
 [[Image:dxmstn.gif]]<br><br>
@@ Line 270: / Line 296: @@
 The following example shows how to annotate your Java class to obtain this mapping with EclipseLink. In this case, the '''@XmlValue''' annotation will be used.
+<div style="width:700px">
 <source lang="java">
 package example;
@@ Line 284: / Line 311: @@
 }
 </source>
+</div>
 The example below shows how to to define your mapping information in EclipseLink's OXM metadata format.
+<div style="width:700px">
 <source lang="xml">
 ...
@@ Line 297: / Line 326: @@
 ...
 </source>
+</div>
 <br><br>
@@ Line 306: / Line 336: @@
 The following XML schema and figure illustrate an XML direct mapping from a '''Calendar''' object in Java to a '''date''' field in XML.
+<div style="width:700px">
 <source lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
@@ Line 320: / Line 351: @@
 </xsd:schema>
 </source>
+</div>
 [[Image:Schematypedate.png]]
@@ Line 325: / Line 357: @@
 The example below shows how to annotate your Java class to obtain this mapping with EclipseLink.  Here, the '''@XmlSchemaType''' is used to specify the datatype that will appear in the marshalled XML.
+<div style="width:700px">
 <source lang="java">
 package example;
@@ Line 340: / Line 373: @@
 }
 </source>
+</div>
 The following example shows how to to define your mapping information in EclipseLink's OXM metadata format.
+<div style="width:700px">
 <source lang="xml">
 ...
@@ Line 355: / Line 390: @@
 ...
 </source>
+</div>
 <br><br>
@@ Line 361: / Line 397: @@
 The next example schema and figure illustrate XML direct mappings to two different text nodes of different binary types.
+<div style="width:700px">
 <source lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
@@ Line 376: / Line 413: @@
 </xsd:schema>
 </source>
+</div>
 [[Image:dxmscht.gif]]<br><br>
@@ Line 381: / Line 419: @@
 The example below shows how to annotate your Java class to obtain this mapping with EclipseLink.  By default, JAXB will marshall '''byte[]''' to '''base64Binary''', so nothing special is needed for the '''resume''' mapping.  To map to a '''hexBinary''' field, the '''@XmlSchemaType''' annotation specifies the XML type, while '''@XmlJavaTypeAdapter''' specifies the adapter class that will be responsible for converting the value (in this case, the built-in JAXB '''HexBinaryAdapter''').
+<div style="width:700px">
 <source lang="java">
 package example;
@@ Line 398: / Line 437: @@
 }
 </source>
+</div>
 The following example shows how to to define your mapping information in EclipseLink's OXM metadata format.
+<div style="width:700px">
 <source lang="xml">
 ...
@@ Line 415: / Line 456: @@
 ...
 </source>
+</div>
 <br><br>
@@ Line 423: / Line 465: @@
 Given the XML schema in this example, the figure below illustrates a Java class that can be mapped to a corresponding XML document.
+<div style="width:700px">
 <source lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
@@ Line 438: / Line 481: @@
 </xsd:schema>
 </source>
+</div>
 [[Image:dxmsttc.gif]]<br><br>
@@ Line 447: / Line 491: @@
 The following example shows shows how to annotate your Java class to obtain this mapping with EclipseLink.
+<div style="width:700px">
 <source lang="java">
 package example;
@@ Line 462: / Line 507: @@
 }
 </source>
+</div>
 The example below shows how to define your mapping information in EclipseLink's OXM metadata format.
+<div style="width:700px">
 <source lang="xml">
 ...
@@ Line 476: / Line 523: @@
 ...
 </source>
+</div>
 For more information, see [[Introduction%20to%20Mappings%20(ELUG)#Simple Type Translator|Simple Type Translator]].

Breadcrumbs

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.

Difference between revisions of "EclipseLink/UserGuide/MOXy/Simple Values/Single Values/XMLDirectMapping"

Revision as of 11:02, 5 July 2011

Contents

Mapping Simple Values

Mapping to an Attribute

Mapping to a Text Node

Mapping to a Text Node in a Simple Sequence

Mapping to a Text Node in a Sub-element

Mapping to a Text Node by Position

Mapping to a Simple Text Node

Mapping to a Specified Schema Type

Using Java Type Adapters

Mapping with a Simple Type Translator