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

From Eclipsepedia

Jump to: navigation, search
Line 7: Line 7:
 
|apis= * [http://www.eclipse.org/eclipselink/api/latest/javax/xml/bind/annotation/XmlElement.html XmlElement]
 
|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]
 
* [http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/oxm/annotations/XmlPath.html XmlPath]
 
 
}}
 
}}
  
=Mapping Privately-Owned One-to-One Relationships=
+
= 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:
 
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">
 
<source lang="xml">
 
<customer>
 
<customer>
Line 24: Line 25:
 
</customer>
 
</customer>
 
</source>
 
</source>
 +
</div>
 +
 +
== Mapping to an Element ==
  
==Mapping to an Element==
 
 
Given the XML schema in this example, the figure below illustrates a one-to-one relationship between two complex types.
 
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">
 
<source lang="xml">
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
Line 46: Line 50:
 
</xsd:schema>
 
</xsd:schema>
 
</source>
 
</source>
 +
</div>
  
 
[[Image:onetoone.png]]<br><br>
 
[[Image:onetoone.png]]<br><br>
Line 53: Line 58:
 
{{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.}}
 
{{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 style="width:700px">
 
<source lang="java">
 
<source lang="java">
 
package example;
 
package example;
Line 67: Line 73:
 
}
 
}
 
</source>
 
</source>
 +
</div>
  
 +
<div style="width:700px">
 
<source lang="java">
 
<source lang="java">
 
package example;
 
package example;
Line 85: Line 93:
 
}
 
}
 
</source>
 
</source>
 +
</div>
  
The following example shows how to define your mapping information in EclipseLink's OXM metadata format.
+
The following example shows how to define your mapping information in an EclipseLink's XML Bindings document.
  
 +
<div style="width:700px">
 
<source lang="xml">
 
<source lang="xml">
 
...
 
...
Line 106: Line 116:
 
...
 
...
 
</source>
 
</source>
 +
</div>
 +
 +
 +
== Using EclipseLink's @XmlPath Annotation ==
  
==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:
 
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">
 
<source lang="java">
 
package example;
 
package example;
Line 124: Line 138:
 
   ...
 
   ...
 
}
 
}
</source>
+
</source>
 +
</div>
  
Using EclipseLink's OXM metadata format:
+
Using EclipseLink XML Bindings:
  
 +
<div style="width:700px">
 
<source lang="xml">
 
<source lang="xml">
 
...
 
...
Line 138: Line 154:
 
...
 
...
 
</source>
 
</source>
 +
</div>
  
 
This will produce the following XML:
 
This will produce the following XML:
  
 +
<div style="width:700px">
 
<source lang="xml">
 
<source lang="xml">
 
<customer>
 
<customer>
Line 150: Line 168:
 
</customer>
 
</customer>
 
</source>
 
</source>
 +
</div>
  
 
You can also use '''@XmlPath''' to map to different occurrences of the same element in XML, by index.  For example:
 
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">
 
<source lang="java">
 
package example;
 
package example;
Line 168: Line 188:
 
   ...
 
   ...
 
}
 
}
</source>
+
</source>
 +
</div>
  
 
will produce the following XML:
 
will produce the following XML:
  
 +
<div style="width:700px">
 
<source lang="xml">
 
<source lang="xml">
 
<customer>
 
<customer>
Line 184: Line 206:
 
</customer>
 
</customer>
 
</source>
 
</source>
 +
</div>
  
  

Revision as of 14:26, 13 July 2011

EclipseLink MOXy

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Contents


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:

<customer>
   <name>Bob Smith</name>
   <id>1982812</id>
   <phone-number>
      <area-code>613</area-code>
      <number>5550210</number>
      <extension>20016</extension>
   </phone-number>
</customer>

Mapping to an Element

Given the XML schema in this example, the figure below illustrates a one-to-one relationship between two complex 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: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>

Onetoone.png

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.

Idea.png
By default, JAXB will assume all fields on your Java object are @XmlElements, 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.


package example;
 
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
   @XmlElement(name="phone-number")
   private PhoneNumber phoneNumber;
 
   ...
}
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;
 
   ...
}

The following example shows how to define your mapping information in an EclipseLink's XML Bindings document.

...
<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>
...


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:

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;
 
   ...
}

Using EclipseLink XML Bindings:

...
<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>
...

This will produce the following XML:

<customer>
   <contact-info>
      <phone-number>
         <number>555-631-2124</number>
      </phone-number>
   </contact-info>
</customer>

You can also use @XmlPath to map to different occurrences of the same element in XML, by index. For example:

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;
   ...
}

will produce the following XML:

<customer>
   <contact-info>
      <phone>
         <number>555-631-2124</number>
      </phone>
      <phone>
         <number>555-631-8298</number>
      </phone>
   </contact-info>
</customer>


Eclipselink-logo.gif
Version: DRAFT
Other versions...