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

From Eclipsepedia

Jump to: navigation, search
(Working with Null Values)
m (Replacing page with 'Please see http://www.eclipse.org/eclipselink/documentation/2.4/moxy/privately_owned_relationships001.htm')
 
(42 intermediate revisions by 2 users 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
+
}}
+
 
+
=Mapping One-to-One Relationships=
+
This section demonstrates several ways to map a one-to-one relationship between objects.
+
 
+
==Mapping to a Complex Type==
+
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="address" type="address-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.  All that is needed is the standard JAXB <tt>@XmlElement</tt> annotation.
+
 
+
<source lang="java">
+
@XmlRootElement
+
public class Customer {
+
  @XmlElement(name="phone-number")
+
  public PhoneNumber phoneNumber;
+
}
+
 
+
public class PhoneNumber {
+
  @XmlElement(name="area-code")
+
  public Integer areaCode;
+
  @XmlElement
+
  public Integer number;
+
  @XmlElement
+
  public Integer extension;
+
}
+
</source>
+
 
+
The example below shows how to 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>
+
 
+
=="Self" Mappings==
+
 
+
EclipseLink allows you to configure your one-to-one mapping such that the data from the target object will appear inside the source object's XML element.  Using the example above, this means that the "<tt>PhoneNumber</tt>" information would appear directly under the "<tt>customer</tt>" element, and not wrapped in a "<tt>phone-number</tt>" element.  This is referred to as a "self" mapping, and is achieved by setting the target object's XPath to "'''.'''" (dot).  The following example demonstrates a self mapping declared in annotations.
+
 
+
<source lang="java">
+
@XmlRootElement
+
public class Customer {
+
  @XmlElement
+
  @XmlPath(".")
+
  public PhoneNumber phoneNumber;
+
}
+
 
+
public class PhoneNumber {
+
  ...
+
}
+
</source>
+
 
+
The example below shows a self mapping defined on EclipseLink OXM metadata format.
+
 
+
<source lang="xml">
+
...
+
<java-type name="Customer">
+
  <xml-root-element name="customer"/>
+
  <java-attributes>
+
      <xml-element java-attribute="phoneNumber" type="PhoneNumber" xml-path="."/>
+
  </java-attributes>
+
</java-type>
+
 
+
<java-type name="PhoneNumber">
+
  ...
+
</java-type>
+
...
+
</source>
+
 
+
Using a self mapping, the following XML will be produced:
+
 
+
<source lang="xml">
+
<customer>
+
  <area-code>613</area-code>
+
  <number>2883000</number>
+
  <extension>1547</extension>
+
</customer>
+
</source>
+
 
+
==Working with Null Values==
+
 
+
Eclipselink offers several ways to configure its handling of null values in both Java and XML.  For example, your XML may use <tt>xsi:nil</tt> to represent a null value (e.g. <tt><first-name xsi:nil="true"/></tt>), or it might simply use an empty element (e.g. <tt><first-name></first-name></tt>).  On the Java side, you may want to specify exactly how a null value should be written to XML (<tt>nil</tt> or empty node).  You can even specify an "isSet" method, to differentiate between values that were explicitly set to null versus values which are null due to being unset.
+
 
+
Consider the following schema:
+
 
+
<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="id" type="xsd:string"/>
+
      <xsd:element name="name" type="xsd:string"/>
+
      <xsd:element name="account-number" type="xsd:string" nillable="true"/>
+
  </xsd:complexType>
+
+
</xsd:schema>
+
</source>
+
 
+
An example instance document might look like:
+
 
+
<source lang="xml">
+
<customer>
+
  <id/>
+
  <name>Jon Smith</name>
+
  <account-number xsi:nil="true"/>
+
</customer>
+
</source>
+
 
+
For this example, we would like:
+
 
+
* Empty <tt>id</tt> tags to correspond to <tt>null</tt> in Java
+
* Empty <tt>name</tt> tags to correspond to "" (empty string) in Java (this is EclipseLink's default null-handling behavior)
+
* A <tt>nil</tt> <tt>account-number</tt> to correspond to <tt>null</tt> in Java
+
 
+
To achieve this behavior in EclipseLink, our mappings can be defined using annotations as follows:
+
 
+
<source lang="java">
+
import org.eclipse.persistence.oxm.annotations.XmlNullPolicy;
+
import org.eclipse.persistence.oxm.annotations.XmlMarshalNullRepresentation;
+
 
+
@XmlRootElement
+
public class Customer {
+
  @XmlElement
+
  public String id;
+
  @XmlElement
+
  public String name;
+
  @XmlElement(name="account-number")
+
  @XmlNullPolicy(xsiNilRepresentNull="true" nullRepresentationForXml=XmlMarshalNullRepresentation.XSI_NIL)
+
  public String accountNumber;
+
}
+
</source>
+
 
+
Here, we have specified that <tt>xsi:nil</tt> in XML should represent <tt>null</tt> in Java, and that <tt>null</tt> in Java should be represented by <tt>xsi:nil</tt>.
+
 
+
{{EclipseLink_MOXy
+
|version=2.2.0 DRAFT
+
|previous=[[EclipseLink/UserGuide/MOXy/Relationships/Privately Owned|Privately owned]]
+
|next=[[EclipseLink/UserGuide/MOXy/Relationships/Privately_Owned/One-to-Many|One-to-many]]
+
|up=[[EclipseLink/UserGuide/MOXy/Relationships/Privately Owned|Privately owned]]
+
}}
+

Latest revision as of 10:21, 8 November 2012

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