org.eclipse.persistence.oxm.annotations.XmlPath Maven / Gradle / Ivy
Show all versions of eclipselink Show documentation
/*
* Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0,
* or the Eclipse Distribution License v. 1.0 which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
*/
// Contributors:
// Matt MacIvor = 2.1 - Initial contribution
package org.eclipse.persistence.oxm.annotations;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* XPath based mapping is what allows an existing object model to be mapped
* to an existing XML schema. The {@code @XmlPath} annotation is the means by
* which XPath based mapping is achieved.
* Example 1 - Using {@code @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
* {@code @XmlElementWrapper}. Here we'll use {@code @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:
* {@code
*
* <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 {@code @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:
* {@code
*
* <customer>
* <address>
* <street>1 Billing Street</street>
* </address>
* <address>
* <street>2 Shipping Road</street>
* </address>
* </customer>
* }
*
* Example 3 - Using {@code @XmlPath} to Map Two Objects to the Same Node
* We have seen how {@code @XmlPath} can be used to expand the structure by
* adding a grouping element. {@code @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:
* {@code
*
* <customer>
* <street>1 Billing Street</street>
* <shippingAddress>
* <street>2 Shipping Road</street>
* </shippingAddress>
* </customer>
* }
*
*/
@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlPath {
/**
* 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 jakarta.xml.bind.annotation.XmlSchema
* @see jakarta.xml.bind.annotation.XmlNs
*/
String value();
}