JAXB and Shared References: @XmlID and @XmlIDREF

When converting objects to XML, privately owned data can easily be represented through nested elements.  When there are multiple references to an object another mechanism needs to be used.  In JAXB this mechanism is @XmlID and @XmlIDREF.

XML is a tree structure so each object has to be represented as a nested element.  In our example we will nest all employees under the company.   This is achieved using @XmlElement.  Note any unnannotated field/property is considered to be @XmlElement.

package blog.shared;

import java.util.ArrayList;
import java.util.List;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Company {

    @XmlElement(name="employee")
    private List<Employee> employees;

    public Company() {
        employees = new ArrayList<Employee>();
    }

}

In addition to each employee object being referenced by a company object, there are also references between employee objects.  Each employee may have one manager and multiple reports.  These relationships will be represented using keys (@XmlID) and foreign keys (@XmlIDREF).

MOXy Extenstion:  The JAXB specification requires that the property marked with @XmlID be a String property, MOXy JAXB does not enforce this restriction.

package blog.shared;

import java.util.ArrayList;
import java.util.List;

import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAttribute;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlID;
import javax.xml.bind.annotation.XmlIDREF;

@XmlAccessorType(XmlAccessType.FIELD)
public class Employee {

    @XmlAttribute
    @XmlID
    private String id;

    @XmlAttribute
    private String name;

    @XmlIDREF
    private Employee manager;

    @XmlElement(name="report")
    @XmlIDREF
    private List<Employee> reports;

    public Employee() {
        reports = new ArrayList<Employee>();
    }

}

The following code will be used to demonstrate the concept.

package blog.shared;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.Marshaller;

public class Demo {

    public static void main(String[] args) throws Exception {
        Company company = new Company();

        Employee employee1 = new Employee();
        employee1.setId("1");
        employee1.setName("Jane Doe");
        company.getEmployees().add(employee1);

        Employee employee2 = new Employee();
        employee2.setId("2");
        employee2.setName("John Smith");
        employee2.setManager(employee1);
        employee1.getReports().add(employee2);
        company.getEmployees().add(employee2);

        Employee employee3 = new Employee();
        employee3.setId("3");
        employee3.setName("Anne Jones");
        employee3.setManager(employee1);
        employee1.getReports().add(employee3);
        company.getEmployees().add(employee3);

        JAXBContext jc = JAXBContext.newInstance(Company.class);

        Marshaller marshaller = jc.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
        marshaller.marshal(company, System.out);
    }

}

In the XML representation the manager and reports are marshalled with the ID of the employee instance they are referencing.

<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 @XmlIDREF annotation is also compatible with the @XmlList annotation. Alternatively we could model our Employee object as:

package blog.shared;

import java.util.ArrayList;
import java.util.List;

import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAttribute;
import javax.xml.bind.annotation.XmlID;
import javax.xml.bind.annotation.XmlIDREF;
import javax.xml.bind.annotation.XmlList;

@XmlAccessorType(XmlAccessType.FIELD)
public class Employee {

    @XmlID
    @XmlAttribute
    private String id;

    @XmlAttribute
    private String name;

    @XmlIDREF
    private Employee manager;

    @XmlIDREF
    @XmlList
    private List<Employee> reports;

    public Employee() {
        reports = new ArrayList<Employee>();
    }

}

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