Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EclipseLink/UserGuide/MOXy/Simple Values/Single Values/XMLDirectMapping
EclipseLink | |
Website | |
Download | |
Community | |
Mailing List • Forums • IRC • mattermost | |
Issues | |
Open • Help Wanted • Bug Day | |
Contribute | |
Browse Source |
Key API
Contents
- 1 XML Direct Mappings
- 1.1 Mapping to an Attribute
- 1.2 Mapping to a Text Node
- 1.3 Mapping to a Specified Schema Type
- 1.4 Mapping to a List Field with an XML Direct Mapping
- 1.5 Mapping with a Simple Type Translator
- 1.6 Mapping to a Union Field with an XML Direct Mapping
- 1.7 Mapping to a Union of Lists with an XML Direct Mapping
- 1.8 Mapping to a Union of Unions with an XML Direct Mapping
XML Direct Mappings
XML direct mappings map a Java attribute directly to XML text nodes. You can use an XML direct mapping in the following scenarios:
- Mapping to an Attribute
- Mapping to a Text Node
- Mapping to a Specified Schema Type
- Mapping to a List Field with an XML Direct Mapping
- Mapping with a Simple Type Translator
- Mapping to a Union Field with an XML Direct Mapping
- Mapping to a Union of Lists with an XML Direct Mapping
- Mapping to a Union of Unions with an XML Direct Mapping
Mapping to an Attribute
Given the XML schema in this example, the XML Direct Mapping to an Attribute figure illustrates an XML direct mapping to an attribute in a corresponding XML document.
Schema for XML Direct Mapping to an Attribute
<?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>
XML Direct Mapping to an Attribute
The Java for XML Direct Mapping to an Attribute example shows how to annotate your Java class to obtain this mapping with EclipseLink. All that is needed is the standard JAXB @XmlAttribute annotation.
Java for XML Direct Mapping to an Attribute
@XmlRootElement public class Customer { @XmlAttribute public Integer id; }
The OXM for XML Direct Mapping to an Attribute example shows how to to define your mapping information in EclipseLink's OXM metadata format.
OXM for XML Direct Mapping to an Attribute
... <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 the Schema for XML Direct Mapping to a Text Node in a Simple Sequence example, the XML Direct Mapping to a Text Node in a Simple Sequence figure illustrates an XML direct mapping to individual text nodes in a sequence in a corresponding XML document.
Schema for XML Direct Mapping to a Text Node in a Simple Sequence
<?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>
XML Direct Mapping to a Text Node in a Simple Sequence
The Java for XML Direct Mapping to a Text Node in a Simple Sequence 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.
Java for XML Direct Mapping to a Text Node in a Simple Sequence
@XmlRootElement public class Customer { @XmlElement(name="first-name") public String firstName; @XmlElement(name="last-name") public String lastName; }
The OXM for XML Direct Mapping to a Text Node in a Simple Sequence example 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.
OXM for XML Direct Mapping to a Text Node in a Simple Sequence
... <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 Subelement
Given the XML schema in the Schema for XML Direct Mapping to a Text Node in a Subelement example, the XML Direct Mapping to a Text Node in a Subelement figure illustrates an XML direct mapping to a text node in a subelement in a corresponding XML document.
Schema for XML Direct Mapping to a Text Node in a Subelement
<?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>
XML Direct Mapping to a Text Node in a Subelement
The Java for XML Direct Mapping to a Text Node in a Subelemen 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.
Java for XML Direct Mapping to a Text Node in a Subelement
@XmlRootElement public class Customer { @XmlPath("personal-info/first-name/text()") public String firstName; @XmlPath("personal-info/last-name/text()") public String lastName; }
The OXM for XML Direct Mapping to a Text Node in a Subelemen example 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.
OXM for XML Direct Mapping to a Text Node in a Subelement
... <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 the Schema for XML Direct Mapping to Text Node by Position exampple, the XML Direct Mapping to Text Node by Position figure illustrates an XML direct mapping to a text node by position in a corresponding XML document.
'Schema for XML Direct Mapping to Text Node by Position
<?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>
XML Direct Mapping to Text Node by Position
The Java for XML Direct Mapping to Text Node by Position example shows how to configure this mapping in Java. Again, for more complex XML path customization, EclipseLink's @XmlPath annotation is used.
Java for XML Direct Mapping to Text Node by Position
@XmlRootElement public class Customer { @XmlPath("name[1]/text()") public String firstName; @XmlPath("name[2]/text()") public String lastName; }
The OXM for XML Direct Mapping to Text Node by Position example shows how to to define your mapping information in EclipseLink's OXM metadata format.
OXM for XML Direct Mapping to Text Node by Position
... <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 the Schema for XML Direct Mapping to Simple Text Node example, the XML Direct Mapping to Simple Text Node figure illustrates an XML direct mapping to a simple text node in a corresponding XML document.
Schema for XML Direct Mapping to Simple Text Node
<?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>
XML Direct Mapping to Simple Text Node
The Java for XML Direct Mapping to Simple Text Node example shows how to annotate your Java class to obtain this mapping with EclipseLink. In this case, the @XmlValue annotation will be used.
Java for XML Direct Mapping to Simple Text Node
@XmlRootElement(name="phone-number") public class PhoneNumber { @XmlValue public String number; }
The OXM for XML Direct Mapping to Simple Text Node example shows how to to define your mapping information in EclipseLink's OXM metadata format.
OXM for XML Direct Mapping to Simple Text Node
... <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.
Given the XML schema in this examaple, the XML Direct Mapping to a Specified Schema Type figure illustrates XML direct mappings to two different text nodes of different binary types.
Schema for XML Direct Mapping to a Specified Schema Type
<?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>
XML Direct Mapping to a Specified Schema Type
The Java for XML Direct Mapping to a Specified Schema Type example 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).
Java for XML Direct Mapping to a Specified Schema Type
@XmlRootElement public class Customer { @XmlElement public byte[] resume; @XmlElement @XmlSchemaType(name="hexBinary") @XmlJavaTypeAdapter(HexBinaryAdapter.class) public byte[] picture; }
The OXM for XML Direct Mapping to a Specified Schema Type example shows how to to define your mapping information in EclipseLink's OXM metadata format.
OXM for XML Direct Mapping to a Specified Schema Type
... <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 to a List Field with an XML Direct Mapping
Given the XML schema in this exmaple, the XMLDirect Mapping to a List Field figure illustrates an XML direct mapping to an xsd:list type in a corresponding XML document when you represent the list in your object model as a String of white space delimited tokens.
Schema for XML Direct Mapping to a List Field
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:element name="employee" type="employee-type"/> <xsd:complexType name="employee-type"> <xsd:sequence> <xsd:element name="tasks" type="tasks-type"/> </xsd:sequence> </xsd:complexType> <xsd:simpleType name="tasks-type"> <xsd:list itemType="xsd:string"/> </xsd:simpleType> </xsd:schema>
XMLDirect Mapping to a List Field
The example below shows how to annotate your Java class to obtain this mapping with EclipseLink.
Java for XML Direct Mapping to a List Field Node
@XmlRootElement public class Employee { @XmlList public List<String> tasks; }
The example below shows how to to define your mapping information in EclipseLink's OXM metadata format.
OXM for XML Direct Mapping to a List Field Node
... <java-type name="Employee"> <xml-root-element name="employee"/> <java-attributes> <xml-element java-attribute="tasks" xml-path="tasks/text()" xml-list="true"/> </java-attributes> </java-type> ...
@XmlList can also be used in conjunction with @XmlAttribute and @XmlValue.
@XmlRootElement public class Customer { @XmlAttribute @XmlList public List<Integer> ids; }
@XmlRootElement(name="phone-numbers") public class PhoneNumbers { @XmlValue @XmlList public List<String> numbers; }
... <java-type name="Customer"> <xml-root-element name="customer"/> <java-attributes> <xml-attribute java-attribute="ids" xml-list="true"/> </java-attributes> </java-type> ... ... <java-type name="PhoneNumbers"> <xml-root-element name="phone-numbers"/> <java-attributes> <xml-value java-attribute="numbers" xml-list="true"/> </java-attributes> </java-type> ...
<customer ids="726 1982 1989 2991"/>
<phone-numbers>6132883982 6139828817 18882982298</phone-numbers>
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 fragment in the Schema for XML Direct Mapping with Simple Type Translator example, the Java Class for XML Direct Mapping with Simple Type Translator figure illustrates a Java class that can be mapped to a corresponding XML document.
Schema for XML Direct Mapping with Simple Type Translator
<?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>
Java Class for XML Direct Mapping with Simple Type Translator
The following figure illustrates an XML direct mapping with a simple type translator in an XML document that conforms to the schema in the Schema for XML Direct Mapping with Simple Type Translator example.
XML Direct Mapping with a Simple Type Translator
The Java for XML Direct Mapping with Simple Type Translator example shows shows how to annotate your Java class to obtain this mapping with EclipseLink.
Java for XML Direct Mapping with Simple Type Translator
@XmlRootElement(name="phone-number") public class PhoneNumber { @XmlElement(name="area-code") public Object areaCode; @XmlElement public Object number; }
The OXM for XML Direct Mapping with Simple Type Translator example shows how to to define your mapping information in EclipseLink's OXM metadata format.
OXM for XML Direct Mapping with Simple Type Translator
... <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.
Mapping to a Union Field with an XML Direct Mapping
Given the XML schema in the Schema for XML Direct Mapping to a Union Field example, the 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 shoeSize attribute in this class: when using a union field, the corresponding attribute must be able to store all possible values.
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>
Java Class for XML Direct Mapping to a Union Field
The 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 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 xsd:decimal. Because "10.5" is a valid decimal, EclipseLink converts the value to the appropriate type. If the Object attribute is specific enough to trigger an appropriate value, EclipseLink will use that type instead. Otherwise, EclipseLink uses a default (in this case BigDecimal). You can override this behavior in Java code.
XML Direct Mapping to the First Valid Union Type
The 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 Schema for XML Direct Mapping to a Union Field. In this document, the value "M" is not a valid xsd:decimal type so the next union type is tried. The next union type is xsd:string and a conversion can be done.
XML Direct Mapping to Another Valid Union Type
This example shows how to configure this mapping in Java.
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 XMLUnionField method addConversion:
shoeSizeField.addConversion(XMLConstants.DECIMAL_QNAME, Float.class);
Mapping to a Union of Lists with an XML Direct Mapping
Given the XML schema in Schema for XML Direct Mapping to Union of Lists, the XML Direct Mapping to Union of Lists figure illustrates an XML direct mapping to a union of lists in a corresponding XML document. The Java for XML Direct Mapping to Union of Lists example shows how to configure this mapping in Java.
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>
XML Direct Mapping to Union of Lists
Note that in this example, valid XML documents contain either all xsd:double, all xsd:date, or all xsd:integer values.
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 Schema for XML Direct Mapping to a Union of Unions example, the 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 Java for XML Direct Mapping to a Union of Unions example shows how to configure this mapping in Java.
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>
Java Class for XML Direct Mapping to a Union of Unions
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 Home MOXy User Guide: Table of Contents, Search | ||
How to contribute to this guide... |