Package org.eclipse.persistence.oxm.annotations

Annotation Type XmlPath

@Target({FIELD,METHOD}) @Retention(RUNTIME) 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 = "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.*;

      Then the following XPath:

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

      Will be qualified as:

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