XPath based mapping is what allows an existing object model to be mapped to an existing XML schema. The @XmlPath annotation is the means by which XPath based mapping is achieved.

Example 1 - Using @XmlPath to Add a Grouping Element

Sometimes grouping elements are added to your document to organise data. JAXB has this concept for collection properties in the form of @XmlElementWrapper. Here we'll use @XmlPath for non-collection properties. In this case we'll nest the billing/shipping address data within the "contact-info" element.

import jakarta.xml.bind.annotation.*;
import org.eclipse.persistence.oxm.annotations.XmlPath;

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
    @XmlPath("contact-info/billing-address")
    private Address billingAddress;

    @XmlPath("contact-info/shipping-address")
    private Address shippingAddress;
}

This will produce XML like:

<customer>
    <contact-info>
        <billing-address>
            <street>1 Billing Street</street>
        </billing-address>
        <shipping-address>
            <street>2 Shipping Road</street>
        </shipping-address>
    </contact-info>
</customer>

Example 2 - Using @XmlPath to Map by Position

Normally in JAXB elements with the same name must be mapped to a collection property. Using the @XmlPath extension you map non-collection properties to a repeated element by index.

import jakarta.xml.bind.annotation.*;
import org.eclipse.persistence.oxm.annotations.XmlPath;

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
    @XmlPath("address[1]")
    private Address billingAddress;

    @XmlPath("address[2]")
    private Address shippingAddress;
}

This will produce XML like:

<customer>
    <address>
        <street>1 Billing Street</street>
    </address>
    <address>
        <street>2 Shipping Road</street>
    </address>
</customer>

Example 3 - Using @XmlPath to Map Two Objects to the Same Node

We have seen how @XmlPath can be used to expand the structure by adding a grouping element. @XmlPath can also be used to collapse the structure by mapping two objects to the same node.

import jakarta.xml.bind.annotation.*;
import org.eclipse.persistence.oxm.annotations.XmlPath;

@XmlRootElement @XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
    @XmlPath(".")
    private Address billingAddress;

    private Address shippingAddress;
}

This will produce XML like:

<customer>
    <street>1 Billing Street</street>
    <shippingAddress>
        <street>2 Shipping Road</street>
    </shippingAddress>
</customer>

@XmlSchema(namespace = "http://www.example.org/FOO",
           xmlns = {@XmlNs(prefix="ns", namespaceURI="http://www.example.com/BAR")},
           elementFormDefault = XmlNsForm.QUALIFIED)
package org.example;

import jakarta.xml.bind.annotation.*;

@XmlPath("contact-info/ns:address/@id")