Difference between revisions of "EclipseLink/UserGuide/MOXy/Relationships/Privately Owned/One-to-One"

From Eclipsepedia

Jump to: navigation, search
m (Replacing page with 'Please see http://www.eclipse.org/eclipselink/documentation/2.4/moxy/privately_owned_relationships001.htm')
 
(5 intermediate revisions by one 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:
+
 
+
<div style="width:700px">
+
<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>
+
</div>
+
 
+
== Mapping to an Element ==
+
 
+
Given the XML schema in this example, the figure below illustrates a one-to-one relationship between two complex types.
+
 
+
<div style="width:700px">
+
<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>
+
</div>
+
 
+
[[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. 
+
 
+
<div style="width:850px">
+
{{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.}}
+
</div>
+
 
+
<div style="width:700px">
+
<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>
+
</div>
+
 
+
<div style="width:700px">
+
<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>
+
</div>
+
 
+
The following example shows how to define your mapping information in an EclipseLink's XML Bindings document.
+
 
+
<div style="width:700px">
+
<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>
+
</div>
+
 
+
 
+
== 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:
+
 
+
<div style="width:700px">
+
<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>
+
</div>
+
 
+
Using EclipseLink XML Bindings:
+
 
+
<div style="width:700px">
+
<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>
+
</div>
+
 
+
This will produce the following XML:
+
 
+
<div style="width:700px">
+
<source lang="xml">
+
<customer>
+
  <contact-info>
+
      <phone-number>
+
        <number>555-631-2124</number>
+
      </phone-number>
+
  </contact-info>
+
</customer>
+
</source>
+
</div>
+
 
+
You can also use '''@XmlPath''' to map to different occurrences of the same element in XML, by index.  For example:
+
 
+
<div style="width:700px">
+
<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>
+
</div>
+
 
+
will produce the following XML:
+
 
+
<div style="width:700px">
+
<source lang="xml">
+
<customer>
+
  <contact-info>
+
      <phone>
+
        <number>555-631-2124</number>
+
      </phone>
+
      <phone>
+
        <number>555-631-8298</number>
+
      </phone>
+
  </contact-info>
+
</customer>
+
</source>
+
</div>
+
 
+
 
+
{{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]]
+
}}
+

Latest revision as of 10:21, 8 November 2012

Please see http://www.eclipse.org/eclipselink/documentation/2.4/moxy/privately_owned_relationships001.htm