org.eclipse.persistence.oxm.annotations

Annotation Type XmlPath

@Target(value={FIELD,METHOD})
@Retention(value=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 javax.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 javax.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 javax.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>

Required Element Summary

Required Elements

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

Element Detail

value

public abstract java.lang.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 javax.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