|
|
(9 intermediate revisions by the same user not shown) |
Line 1: |
Line 1: |
− | {{EclipseLink_UserGuide
| + | Please see http://www.eclipse.org/eclipselink/documentation/2.4/moxy/privately_owned_relationships001.htm |
− | |eclipselink=y
| + | |
− | |eclipselinktype=MOXy
| + | |
− | |info=y
| + | |
− | |toc=y
| + | |
− | |api=y
| + | |
− | |apis= * [http://www.eclipse.org/eclipselink/api/latest/javax/xml/bind/annotation/XmlElement.html XmlElement]
| + | |
− | * [http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/oxm/annotations/XmlPath.html XmlPath]
| + | |
− | | + | |
− | }}
| + | |
− | | + | |
− | =Mapping Privately-Owned One-to-One Relationships=
| + | |
− | This section demonstrates several ways to map a one-to-one relationship between objects. By default, one-to-one relationships are privately-owned in JAXB -- their XML content will appear nested inside the owning element. For example, a '''Customer''' with a one-to-one mapping to a '''PhoneNumber''' would be marshalled as:
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | <customer>
| + | |
− | <name>Bob Smith</name>
| + | |
− | <id>1982812</id>
| + | |
− | <phone-number>
| + | |
− | <area-code>613</area-code>
| + | |
− | <number>5550210</number>
| + | |
− | <extension>20016</extension>
| + | |
− | </phone-number>
| + | |
− | </customer>
| + | |
− | </source>
| + | |
− | | + | |
− | ==Mapping to an Element==
| + | |
− | Given the XML schema in this example, the figure below illustrates a one-to-one relationship between two complex types.
| + | |
− | | + | |
− | <source lang="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:element name="phone-number" type="phone-type"/>
| + | |
− | </xsd:complexType>
| + | |
− | | + | |
− | <xsd:complexType name="phone-type">
| + | |
− | <xsd:element name="area-code" type="xsd:int"/>
| + | |
− | <xsd:element name="number" type="xsd:int"/>
| + | |
− | <xsd:element name="extension" type="xsd:int"/>
| + | |
− | </xsd:complexType>
| + | |
− | | + | |
− | </xsd:schema>
| + | |
− | </source>
| + | |
− | | + | |
− | [[Image:onetoone.png]]<br><br>
| + | |
− | | + | |
− | The following example shows how to annotate your Java class to obtain this mapping with EclipseLink. The standard JAXB '''@XmlElement''' annotation can be used to indicate that the associated Java field should be mapped to an XML element.
| + | |
− | | + | |
− | {{tip||By default, JAXB will assume all fields on your Java object are '''@XmlElement'''s, so in many cases the annotation itself is not required. If, however, you want to customize the Java field's XML name, you can specify an '''@XmlElement''' annotation with a '''name''' argument.}}
| + | |
− | | + | |
− | <source lang="java">
| + | |
− | package example;
| + | |
− | | + | |
− | import javax.xml.bind.annotation.*;
| + | |
− | | + | |
− | @XmlRootElement
| + | |
− | @XmlAccessorType(XmlAccessType.FIELD)
| + | |
− | public class Customer {
| + | |
− | @XmlElement(name="phone-number")
| + | |
− | private PhoneNumber phoneNumber;
| + | |
− | | + | |
− | ...
| + | |
− | }
| + | |
− | </source>
| + | |
− | | + | |
− | <source lang="java">
| + | |
− | package example;
| + | |
− | | + | |
− | import javax.xml.bind.annotation.*;
| + | |
− | | + | |
− | @XmlAccessorType(XmlAccessType.FIELD)
| + | |
− | public class PhoneNumber {
| + | |
− | @XmlElement(name="area-code")
| + | |
− | private Integer areaCode;
| + | |
− | | + | |
− | private Integer number;
| + | |
− | | + | |
− | private Integer extension;
| + | |
− | | + | |
− | ...
| + | |
− | }
| + | |
− | </source>
| + | |
− | | + | |
− | The following example shows how to define your mapping information in EclipseLink's OXM metadata format.
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | ...
| + | |
− | <java-type name="Customer">
| + | |
− | <xml-root-element name="customer"/>
| + | |
− | <java-attributes>
| + | |
− | <xml-element java-attribute="phoneNumber" name="phone-number" type="PhoneNumber"/>
| + | |
− | </java-attributes>
| + | |
− | </java-type>
| + | |
− | | + | |
− | <java-type name="PhoneNumber">
| + | |
− | <java-attributes>
| + | |
− | <xml-value java-attribute="areaCode" name="area-code" type="java.lang.Integer"/>
| + | |
− | <xml-value java-attribute="number" type="java.lang.Integer"/>
| + | |
− | <xml-value java-attribute="extension" type="java.lang.Integer"/>
| + | |
− | </java-attributes>
| + | |
− | </java-type>
| + | |
− | ...
| + | |
− | </source>
| + | |
− | | + | |
− | ==Using EclipseLink's @XmlPath Annotation==
| + | |
− | By default, your Java attributes will be mapped to XML based on their attributes Java name, or by a name specified in an '''@XmlElement''' annotation. This mapping is based on XPath, and EclipseLink's '''@XmlPath''' annotation allows you to customize this mapping. For example, you can use it to control the nesting of your elements in XML:
| + | |
− | | + | |
− | <source lang="java">
| + | |
− | package example;
| + | |
− | | + | |
− | import javax.xml.bind.annotation.*;
| + | |
− | import org.eclipse.persistence.oxm.annotations.*;
| + | |
− | | + | |
− | @XmlRootElement
| + | |
− | @XmlAccessorType(XmlAccessType.FIELD)
| + | |
− | public class Customer {
| + | |
− | @XmlPath("contact-info/phone-number")
| + | |
− | private PhoneNumber phoneNumber;
| + | |
− | | + | |
− | ...
| + | |
− | }
| + | |
− | </source>
| + | |
− | | + | |
− | Using EclipseLink's OXM metadata format:
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | ...
| + | |
− | <java-type name="Customer">
| + | |
− | <xml-root-element name="customer"/>
| + | |
− | <java-attributes>
| + | |
− | <xml-element java-attribute="phoneNumber" name="phone-number" type="PhoneNumber" xml-path="contact-info/phone-number"/>
| + | |
− | </java-attributes>
| + | |
− | </java-type>
| + | |
− | ...
| + | |
− | </source>
| + | |
− | | + | |
− | This will produce the following XML:
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | <customer>
| + | |
− | <contact-info>
| + | |
− | <phone-number>
| + | |
− | <number>555-631-2124</number>
| + | |
− | </phone-number>
| + | |
− | </contact-info>
| + | |
− | </customer>
| + | |
− | </source>
| + | |
− | | + | |
− | You can also use '''@XmlPath''' to map to different occurrences of the same element in XML, by index. For example:
| + | |
− | | + | |
− | <source lang="java">
| + | |
− | package example;
| + | |
− | | + | |
− | import javax.xml.bind.annotation.*;
| + | |
− | import org.eclipse.persistence.oxm.annotations.*;
| + | |
− | | + | |
− | @XmlRootElement
| + | |
− | @XmlAccessorType(XmlAccessType.FIELD)
| + | |
− | public class Customer {
| + | |
− | @XmlPath("contact-info/phone[1]")
| + | |
− | private PhoneNumber homePhone;
| + | |
− | @XmlPath("contact-info/phone[2]")
| + | |
− | private PhoneNumber workPhone;
| + | |
− | ...
| + | |
− | }
| + | |
− | </source>
| + | |
− | | + | |
− | will produce the following XML:
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | <customer>
| + | |
− | <contact-info>
| + | |
− | <phone>
| + | |
− | <number>555-631-2124</number>
| + | |
− | </phone>
| + | |
− | <phone>
| + | |
− | <number>555-631-8298</number>
| + | |
− | </phone>
| + | |
− | </contact-info>
| + | |
− | </customer>
| + | |
− | </source>
| + | |
− | | + | |
− | | + | |
− | {{EclipseLink_MOXy
| + | |
− | |previous=[[EclipseLink/UserGuide/MOXy/Simple Values/Special Schema Types/Unions|Unions]]
| + | |
− | |next= [[EclipseLink/UserGuide/MOXy/Relationships/Privately Owned/One-to-Many|Mapping One-to-Many Relationships]]
| + | |
− | }}
| + | |