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.
Difference between revisions of "EclipseLink/UserGuide/MOXy/Simple Values/Single Values/XMLDirectMapping"
Line 31: | Line 31: | ||
[[Image:dxmatt.gif]]<br><br> | [[Image:dxmatt.gif]]<br><br> | ||
− | The following example shows how to annotate your Java class to obtain this mapping with EclipseLink. All that is needed is the standard JAXB | + | 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. |
<source lang="java"> | <source lang="java"> | ||
Line 93: | Line 93: | ||
[[Image:dxmss.gif]]<br><br> | [[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 | + | 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. |
<source lang="java"> | <source lang="java"> | ||
Line 116: | Line 116: | ||
− | The example below shows how to to define your mapping information in EclipseLink's OXM metadata format. To specify a custom element name, the | + | 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. |
<source lang="xml"> | <source lang="xml"> | ||
Line 160: | Line 160: | ||
[[Image:dxmse.gif]]<br><br> | [[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 | + | 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. |
<source lang="java"> | <source lang="java"> | ||
Line 181: | Line 181: | ||
</source> | </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 | + | 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. |
<source lang="xml"> | <source lang="xml"> | ||
Line 217: | Line 217: | ||
[[Image:dxmpos.gif]]<br><br> | [[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 | + | The example below shows how to configure this mapping in Java. Again, for more complex XML path customization, EclipseLink's '''@XmlPath''' annotation is used. |
<source lang="java"> | <source lang="java"> | ||
Line 268: | Line 268: | ||
[[Image:dxmstn.gif]]<br><br> | [[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 | + | 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. |
<source lang="java"> | <source lang="java"> | ||
Line 301: | Line 301: | ||
==Mapping to a Specified Schema 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 <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. | 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 | + | The following XML schema and figure illustrate an XML direct mapping from a '''Calendar''' object in Java to a '''date''' field in XML. |
<source lang="xml"> | <source lang="xml"> | ||
Line 322: | Line 323: | ||
[[Image:Schematypedate.png]] | [[Image:Schematypedate.png]] | ||
− | The example below shows how to annotate your Java class to obtain this mapping with EclipseLink. Here, the | + | 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. |
<source lang="java"> | <source lang="java"> | ||
Line 378: | Line 379: | ||
[[Image:dxmscht.gif]]<br><br> | [[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 | + | 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'''). |
<source lang="java"> | <source lang="java"> | ||
Line 418: | Line 419: | ||
==Mapping with a Simple Type Translator== | ==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 | + | 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. | Given the XML schema in this example, the figure below illustrates a Java class that can be mapped to a corresponding XML document. |
Revision as of 11:36, 20 April 2011
EclipseLink MOXy
EclipseLink | |
Website | |
Download | |
Community | |
Mailing List • Forums • IRC • mattermost | |
Issues | |
Open • Help Wanted • Bug Day | |
Contribute | |
Browse Source |
Key API
Contents
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; ... }
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.