Developing JAXB Applications Using EclipseLink MOXy, Release 2.4
  Go To Table Of Contents
 Search
 PDF

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 Example 4-1, Figure 4-1 illustrates an XML direct mapping to an attribute in a corresponding XML document.

Example 4-1 Sample XML Schema

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

Figure 4-1 XML Direct Mapping to an Attribute

XML Direct Mapping to an Attribute
Description of "Figure 4-1 XML Direct Mapping to an Attribute"

Example 4-2 shows how to annotate your Java class to obtain this mapping with EclipseLink. All that is needed is the standard JAXB @XmlAttribute annotation.

Example 4-2 Using the @XmlAttribute Annotation

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

Example 4-3 shows how to define your mapping information in EclipseLink's OXM metadata format.

Example 4-3 Defining the Mapping

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

Given the XML schema in Example 4-4, Figure 4-2 illustrates an XML direct mapping to individual text nodes in a sequence in a corresponding XML document.

Example 4-4 Sample XML Schema

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

Figure 4-2 XML Direct Mapping to Individual Text Nodes

XML Direct Mapping to Individual Text Nodes
Description of "Figure 4-2 XML Direct Mapping to Individual Text Nodes"

Example 4-1 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.

Example 4-5 Using the @XmlElement Annotation

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 Example 4-5, 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; 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) Specification (http://jcp.org/en/jsr/detail?id=222).

Example 4-6 shows how to define your mapping information in EclipseLink's OXM metadata format. To specify a custom element name, the name attribute is used.

Example 4-6 Using the name Attribute

...
<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 Example 4-7, Figure 4-3 illustrates an XML direct mapping to a text node in a subelement in a corresponding XML document.

Example 4-7 Sample XML Schema

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

Figure 4-3 XML Direct Mapping to a Text Element in a Subnode

XML Direct Mapping to a Text Element in a Subnode
Description of "Figure 4-3 XML Direct Mapping to a Text Element in a Subnode"

Example 4-8 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.

Example 4-8 Using the @XmlPath Annotation

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

Example 4-9 shows how to define your mapping information in EclipseLink's OXM metadata format. Here, the customized XML path is defined in the xml-path attribute.

Example 4-9 Using 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 Example 4-10, Figure 4-4 illustrates an XML direct mapping to a text node by position in a corresponding XML document.

Example 4-10 Sample XML Schema

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

Figure 4-4 XML Direct Mapping to a Text Node

XML Direct Mapping to a Text Node
Description of "Figure 4-4 XML Direct Mapping to a Text Node"

Example 4-11 shows how to configure this mapping in Java. Again, for more complex XML path customization, EclipseLink's @XmlPath annotation is used.

Example 4-11 Using the @XmlPath Annotation

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

Example 4-12 shows how to define your mapping information in EclipseLink's OXM metadata format.

Example 4-12 Defining the Mapping

...
<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 Example 4-13, Figure 4-5 illustrates an XML direct mapping to a simple text node in a corresponding XML document.

Example 4-13 Sample XML Schema

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

Figure 4-5 XML Direct Mapping to a Simple Text Node

XML Direct Mapping to a Simple Text Node
Description of "Figure 4-5 XML Direct Mapping to a Simple Text Node"

Example 4-14 shows how to annotate your Java class to obtain this mapping with EclipseLink. In this case, the @XmlValue annotation will be used.

Example 4-14 Using the @XmlValue Annotation

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

Example 4-15 shows how to define your mapping information in EclipseLink's OXM metadata format.

Example 4-15 Defining the Mapping

...
<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 XML schema in Example 4-16 and Figure 4-6 an XML direct mapping from a Calendar object in Java to a date field in XML.

Example 4-16 Sample XML Schema

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

Figure 4-6 XML Direct Mapping to a Specific Schema Type

XML Direct Mapping to a Specific Schema Type
Description of "Figure 4-6 XML Direct Mapping to a Specific Schema Type"

Example 4-17 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.

Example 4-17 Using the @XmlSchemaType Annotation

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

Example 4-18 shows how to define your mapping information in EclipseLink's OXM metadata format.

Example 4-18 Defining the Mapping

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

Example 4-19 and Figure 4-7 illustrate XML direct mappings to two different text nodes of different binary types.

Example 4-19 Sample XML Schema

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

Figure 4-7 XML Direct Mappings to Different Text Nodes of Different Binary Types

Description of Figure 4-7 follows
Description of "Figure 4-7 XML Direct Mappings to Different Text Nodes of Different Binary Types"

Example 4-20 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).

Example 4-20 Using the @XmlSchemaType and @XmlJavaTypeAdapter Annotations

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

Example 4-21 shows how to define your mapping information in EclipseLink's OXM metadata format.

Example 4-21 Defining the Mapping

...
<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 Example 4-22, Figure 4-8 illustrates a Java class that can be mapped to a corresponding XML document.

Example 4-22 Sample XML Schema

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

Figure 4-8 Sample Java Class

Sample Java Class
Description of "Figure 4-8 Sample Java Class"

Figure 4-9 illustrates an XML direct mapping with a simple type translator in an XML document that conforms to the schema above.

Figure 4-9 XML Direct Mapping with Simple Type Translator

XML Direct Mapping with Simple Type Translator
Description of "Figure 4-9 XML Direct Mapping with Simple Type Translator"

Example 4-23 shows how to annotate your Java class to obtain this mapping with EclipseLink.

Example 4-23 Sample Mapping

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

Example 4-24 shows how to define your mapping information in EclipseLink's OXM metadata format.

Example 4-24 Sample XML Mapping

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