Revision as of 15:53, 16 March 2011

EclipseLink
Website
Download
Community
Mailing List • Forums • IRC • mattermost
Issues
Open • Help Wanted • Bug Day
Contribute
Browse Source

Key API

• javax.xml.bind.annotation.XmlAccessType
• javax.xml.bind.annotation.XmlCustomizer
• javax.xml.bind.annotation.XmlInverseReference

Mapping Composite Key Relationships

If the objects that you want to map have multi-part keys (i.e., a combination of fields that determines uniqueness), you can use EclipseLink's @XmlKey and @XmlJoinNodes to set up this relationship.

One or more @XmlKey annotations can be used to declare the primary keys in a given class. For a single key, either @XmlID or @XmlKey can be used. For composite primary keys, multiple @XmlKey annotations can be used, or a single @XmlID can be combined with one or more @XmlKey annotations.

In this example, each Employee has one manager but multiple reports, and Employees are uniquely identified by the combination of their id and name fields.

@XmlAccessorType(XmlAccessType.FIELD)
public class Employee {
    @XmlID
    @XmlAttribute
    private Integer id;
 
    @XmlKey
    @XmlAttribute
    private String name;
 
    @XmlJoinNodes( {
        @XmlJoinNode(xmlPath = "manager/@id", referencedXmlPath = "@id"),
        @XmlJoinNode(xmlPath = "manager/@name", referencedXmlPath = "@name") })
    public Employee manager;
 
    @XmlJoinNodes( {
        @XmlJoinNode(xmlPath = "report/@id", referencedXmlPath = "@id"),
        @XmlJoinNode(xmlPath = "report/@name", referencedXmlPath = "@name") })
    public List<Employee> reports = new ArrayList<Employee>();
 
    ...
}

The following example shows how to define this mapping information in EclipseLink's OXM metadata format.

...
<java-type name="Employee">
   <java-attributes>
      <xml-attribute java-attribute="id" type="java.lang.Integer" xml-id="true"/>
      <xml-attribute java-attribute="name" type="java.lang.String"/>
      <xml-element java-attribute="manager" type="mypackage.Employee" xml-idref="true"/>
      <xml-element java-attribute="reports" type="mypackage.Employee" container-type="java.util.ArrayList" xml-idref="true"/>
   </java-attributes>
</java-type>
...

This would produce the following XML:

<company>
    <employee id="1" name="Jane Doe">
        <report>2</report>
        <report>3</report>
    </employee>
    <employee id="2" name="John Smith">
        <manager>1</manager>
    </employee>
    <employee id="3" name="Anne Jones">
        <manager>1</manager>
    </employee>
</company>

The manager and reports elements contain the IDs of the Employee instances they are referencing.

Using @XmlList

Because the @XmlIDREF annotation is also compatible with the @XmlList annotation, the Employee object could be modeled as:

@XmlAccessorType(XmlAccessType.FIELD)
public class Employee {
    @XmlID
    @XmlAttribute
    private Integer id;
 
    @XmlAttribute
    private String name;
 
    @XmlIDREF
    private Employee manager;
 
    @XmlIDREF
    @XmlList
    private List<Employee> reports;
 
    ... 
}

This would produce the following XML:

<company>
   <employee id="1" name="Jane Doe">
      <reports>2 3</reports>
   </employee>
   <employee id="2" name="John Smith">
      <manager>1</manager>
   </employee>
   <employee id="3" name="Anne Jones">
      <manager>1</manager>
   </employee>
</company>

Single Key	Keys and Foreign Keys	Embedded Key Class
EclipseLink Home MOXy User Guide: Table of Contents, Search
How to contribute to this guide...