Module eclipselink
Package org.eclipse.persistence.oxm.annotations

Annotation Interface XmlPath

@Target({FIELD,METHOD}) @Retention(RUNTIME) @Repeatable(XmlPaths.class) public @interface XmlPath
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: 
 <xmp>
   <customer>
     <contact-info>
       <billing-address>
         <street>1 Billing Street</street>
       </billing-address>
       <shipping-address>
         <street>2 Shipping Road</street>
       </shipping-address>
     </contact-info>
   </customer>
 </xmp>

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: 
 <xmp>
   <customer>
     <address>
       <street>1 Billing Street</street>
     </address>
     <address>
       <street>2 Shipping Road</street>
     </address>
   </customer>
 </xmp>

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: 
 <xmp>
   <customer>
     <street>1 Billing Street</street>
     <shippingAddress>
       <street>2 Shipping Road</street>
     </shippingAddress>
   </customer>
 </xmp>

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    value
    The XPath for this property.

  • Element Details

    • value

      String value
      The XPath for this property. A subset of the XPath specification may be used to specify mappings. The following concepts are supported:
      • Attribute - "@id"
      • Element - "address"
      • Element by Position - "address[1]"
      • Element by Predicate - "address[@type='mailing']"
      • Element Text - "name/text()"
      • Text - "text()"
      • Self - "."
      • Combination - "personal-info/name[2]/text()"

      For namespace qualified nodes, the prefixes defined in the XmlNs annotations can be used to qualify the XPath fragments. Unqualified fragments will assumed to be in the namespace specified using XmlSchema.

      Example:

      Assuming the following namespace information has been set up using the XmlSchema annotation:

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

 import jakarta.xml.bind.annotation.*;

      Then the following XPath:

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

      Will be qualified as:

      • contact-info - in "https://www.example.org/FOO" namespace.
      • address - in "https://www.example.com/BAR" namespace.
      • @id - in no namespace.
      See Also:
      • XmlSchema
      • XmlNs