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.
EclipseLink/UserGuide/MOXy/Relationships/Privately Owned/One-to-One
EclipseLink MOXy
EclipseLink | |
Website | |
Download | |
Community | |
Mailing List • Forums • IRC • mattermost | |
Issues | |
Open • Help Wanted • Bug Day | |
Contribute | |
Browse Source |
Key API
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>
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.
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 EclipseLink's OXM metadata format.
... <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's OXM metadata format:
... <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>
"Self" Mappings
EclipseLink allows you to configure your one-to-one mapping so the data from the target object will appear inside the source object's XML element. Using the previous example, the PhoneNumber information would appear directly under the customer element, and not wrapped in a phone-number 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.
package example; import javax.xml.bind.annotation.*; import org.eclipse.persistence.oxm.annotations.*; @XmlRootElement @XmlAccessorType(XmlAccessType.FIELD) public class Customer { @XmlPath(".") private PhoneNumber phoneNumber; ... }
public class PhoneNumber { ... }
The following below shows a self mapping defined in EclipseLink's OXM metadata format.
... <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> ...
Using a self mapping, EclipseLink produces the following XML:
<customer> <area-code>613</area-code> <number>2883000</number> <extension>1547</extension> </customer>