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"

Line 441: Line 441:
  
 
For more information, see [[Introduction%20to%20Mappings%20(ELUG)#Simple Type Translator|Simple Type Translator]].
 
For more information, see [[Introduction%20to%20Mappings%20(ELUG)#Simple Type Translator|Simple Type Translator]].
−
 
−
<br><br>
 
−
 
−
==Mapping to a Union Field with an XML Direct Mapping==
 
−
Given the XML schema in the [[#Example 58-16|Schema for XML Direct Mapping to a Union Field]] example, the [[#Figure 58-8|Java Class for XML Direct Mapping to a Union Field]] figure illustrates a Java class that can be mapped to a corresponding XML document. Note the <tt>shoeSize</tt> attribute in this class: when using a union field, the corresponding attribute must be able to store all possible values.
 
−
 
−
<span id="Example 58-16"></span>
 
−
''''' Schema for XML Direct Mapping to Union of Lists'''''
 
−
<?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="shoe-size" type="size-type"/>
 
−
      </xsd:sequence>
 
−
  </xsd:complexType>
 
−
  <xsd:simpleType name="size-type">
 
−
      <xsd:union memberTypes="xsd:decimal xsd:string"/>
 
−
  </xsd:simpleType>
 
−
</xsd:schema>
 
−
 
−
 
−
<span id="Figure 58-8"></span>
 
−
'''''Java Class for XML Direct Mapping to a Union Field'''''
 
−
 
−
[[Image:dxmuc.gif]]<br><br>
 
−
 
−
The [[#Figure 58-9| XML Direct Mapping to the First Valid Union Type]] figure  illustrates an XML direct mapping to a union field in an XML document that conforms to the schema in the [[#Example 58-16|Schema for XML Direct Mapping to a Union Field]] example. When EclipseLink unmarshalls the XML document, it tries each of the union types until it can make a successful conversion. The first schema type in the union is <tt>xsd:decimal</tt>. Because "10.5" is a valid decimal, EclipseLink converts the value to the appropriate type. If the <tt>Object</tt> attribute is specific enough to trigger an appropriate value, EclipseLink will use that type instead. Otherwise, EclipseLink uses a default (in this case <tt>BigDecimal</tt>). You can override this behavior in Java code.
 
−
 
−
<span id="Figure 58-9"></span>
 
−
'''''XML Direct Mapping to the First Valid Union Type'''''
 
−
 
−
[[Image:dxmuv.gif]]<br><br>
 
−
 
−
The [[#Figure 58-10|XML Direct Mapping to Another Valid Union Type]] figure illustrates an XML direct mapping to union field in another XML document that conforms to the schema in [[#Example 58-16|Schema for XML Direct Mapping to a Union Field]]. In this document, the value "M" is not a valid <tt>xsd:decimal</tt> type so the next union type is tried. The next union type is <tt>xsd:string</tt> and a conversion can be done.
 
−
 
−
<span id="Figure 58-10"></span>
 
−
'''''XML Direct Mapping to Another Valid Union Type'''''
 
−
 
−
[[Image:dxmuvs.gif]]<br><br>
 
−
 
−
This example shows how to configure this mapping in Java.
 
−
 
−
<span id="Example 58-17"></span>
 
−
'''''Java for XML Direct Mapping to a Union Type'''''
 
−
XMLDirectMapping shoeSizeMapping = new XMLDirectMapping();
 
−
shoeSizeMapping.setAttributeName("shoeSize");
 
−
XMLUnionField shoeSizeField = new XMLUnionField();
 
−
shoeSizeField.setXPath("shoe-size/text()");
 
−
shoeSizeField.addSchemaType(XMLConstants.DECIMAL_QNAME);
 
−
shoeSizeField.addSchemaType(XMLConstants.STRING_QNAME);
 
−
shoeSizeMapping.setField(shoeSizeField);
 
−
 
−
To override the default conversion, use the <tt>XMLUnionField</tt> method <tt>addConversion</tt><nowiki>:</nowiki>
 
−
shoeSizeField.addConversion(XMLConstants.DECIMAL_QNAME, Float.class);
 
−
 
−
==Mapping to a Union of Lists with an XML Direct Mapping==
 
−
Given the XML schema in [[#Example 58-18|Schema for XML Direct Mapping to Union of Lists]], the [[#Figure 58-11|XML Direct Mapping to Union of Lists]] figure illustrates an XML direct mapping to a union of lists in a corresponding XML document. The [[#Example 58-19|Java for XML Direct Mapping to Union of Lists]] example shows how to configure this mapping in Java.
 
−
 
−
 
−
<span id="Example 58-18"></span>
 
−
''''' Schema for XML Direct Mapping to Union of Lists'''''
 
−
<?xml version="1.0" encoding="UTF-8"?>
 
−
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
−
 
−
    <xsd:element name="vacation" type="unionOfLists"/>
 
−
    <xsd:simpleType name="unionOfLists">
 
−
        <xsd:union memberTypes="xsd:double">
 
−
            <xsd:simpleType>
 
−
                <xsd:list itemType="xsd:date"/>
 
−
            </xsd:simpleType>
 
−
 
−
            <xsd:simpleType>
 
−
                <xsd:list itemType="xsd:integer"/>
 
−
            </xsd:simpleType>
 
−
        </xsd:union>
 
−
    </xsd:simpleType>
 
−
</xsd:schema>
 
−
 
−
 
−
 
−
<span id="'Figure 58-11"></span>
 
−
''''' XML Direct Mapping to Union of Lists'''''
 
−
 
−
[[Image:dxuofl.gif]]<br><br>
 
−
 
−
Note that in this example, valid XML documents contain either all <tt>xsd:double</tt>, all <tt>xsd:date</tt>, or all <tt>xsd:integer</tt> values.
 
−
 
−
 
−
<span id="Example 58-19"></span>
 
−
''''' Java for XML Direct Mapping to Union of Lists'''''
 
−
XMLDirectMapping mapping = new XMLDirectMapping();
 
−
mapping.setAttributeName("vacation");
 
−
mapping.setXPath("UnionOfLists/text()");
 
−
 
−
==Mapping to a Union of Unions with an XML Direct Mapping==
 
−
Given the XML schema in the [[#Example 58-20|Schema for XML Direct Mapping to a Union of Unions]] example, the [[#Figure 58-12|Java Class for XML Direct Mapping to a Union of Unions]] figure illustrates a Java class that can be mapped to a corresponding XML document. The [[#Example 58-21|Java for XML Direct Mapping to a Union of Unions]] example shows how to configure this mapping in Java.
 
−
 
−
 
−
<span id="Example 58-20"></span>
 
−
''''' Schema for XML Direct Mapping to a Union of Unions'''''
 
−
<?xml version="1.0" encoding="UTF-8"?>
 
−
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
−
    <xsd:element name="vacation" type="unionOfUnions"/>
 
−
    <xsd:simpleType name="unionOfUnions">
 
−
        <xsd:union>
 
−
 
−
            <xsd:simpleType>
 
−
                <xsd:union>
 
−
                    <xsd:simpleType>
 
−
                        <xsd:list itemType="xsd:date"/>
 
−
                    </xsd:simpleType>
 
−
                    <xsd:simpleType>
 
−
 
−
                        <xsd:list itemType="xsd:integer"/>
 
−
                    </xsd:simpleType>
 
−
                </xsd:union>
 
−
            </xsd:simpleType>
 
−
            <xsd:simpleType>
 
−
                <xsd:union>
 
−
 
−
                    <xsd:simpleType>
 
−
                        <xsd:list itemType="xsd:string"/>
 
−
                    </xsd:simpleType>
 
−
                    <xsd:simpleType>
 
−
                        <xsd:list itemType="xsd:float"/>
 
−
                    </xsd:simpleType>
 
−
 
−
                </xsd:union>
 
−
            </xsd:simpleType>
 
−
        </xsd:union>
 
−
    </xsd:simpleType>
 
−
</xsd:schema>
 
−
 
−
 
−
<span id="Figure 58-12"></span>
 
−
''''' Java Class for XML Direct Mapping to a Union of Unions'''''
 
−
 
−
[[Image:dxuofu.gif]]<br><br>
 
−
 
−
 
−
<span id="Example 58-21"></span>
 
−
''''' Java for XML Direct Mapping to a Union of Unions'''''
 
−
XMLDirectMapping vacationMapping = new XMLDirectMapping();
 
−
vacationMapping.setAttributeName("vacation");
 
−
XMLUnionField vacationField = new XMLUnionField();
 
−
vacationField.setXPath("vacation/text()");
 
−
vacationField.addSchemaType(XMLConstants.DATE_QNAME);
 
−
vacationField.addSchemaType(XMLConstants.INTEGER_QNAME);
 
−
vacationField.addSchemaType(XMLConstants.STRING_QNAME);
 
−
vacationField.addSchemaType(XMLConstants.FLOAT_QNAME);
 
−
vacationMapping.setField(vacationField);
 
−
 
  
 
{{EclipseLink_MOXy
 
{{EclipseLink_MOXy

Revision as of 15:17, 19 January 2011

EclipseLink MOXy

Eclipselink-logo.gif
EclipseLink
Website
Download
Community
Mailing List • Forums • IRC • mattermost
Issues
Open • Help Wanted • Bug Day
Contribute
Browse Source

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>

Dxmatt.gif

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. 

@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

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>

Dxmss.gif

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. 

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
   @XmlElement(name="first-name")
   private String firstName;
 
   @XmlElement(name="last-name")
   private String lastName;
 
   ...
}
Idea.png
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>

Dxmse.gif

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. 

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

Dxmpos.gif

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

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

Dxmstn.gif

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. 

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

Schematypedate.png

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. 

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

Dxmscht.gif

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

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

Dxmsttc.gif

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

Dxmsttm.gif

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

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

Eclipselink-logo.gif
Version: 2.2.0
Other versions...

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

Copyright © Eclipse Foundation, Inc. All Rights Reserved.