ohair@286: /* mkos@397: * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved. ohair@286: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. ohair@286: * ohair@286: * This code is free software; you can redistribute it and/or modify it ohair@286: * under the terms of the GNU General Public License version 2 only, as ohair@286: * published by the Free Software Foundation. Oracle designates this ohair@286: * particular file as subject to the "Classpath" exception as provided ohair@286: * by Oracle in the LICENSE file that accompanied this code. ohair@286: * ohair@286: * This code is distributed in the hope that it will be useful, but WITHOUT ohair@286: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or ohair@286: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License ohair@286: * version 2 for more details (a copy is included in the LICENSE file that ohair@286: * accompanied this code). ohair@286: * ohair@286: * You should have received a copy of the GNU General Public License version ohair@286: * 2 along with this work; if not, write to the Free Software Foundation, ohair@286: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. ohair@286: * ohair@286: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@286: * or visit www.oracle.com if you need additional information or have any ohair@286: * questions. ohair@286: */ ohair@286: ohair@286: package javax.xml.bind.annotation; ohair@286: ohair@286: import java.lang.annotation.Target; ohair@286: import java.lang.annotation.Retention; ohair@286: import static java.lang.annotation.ElementType.*; ohair@286: import static java.lang.annotation.RetentionPolicy.*; ohair@286: ohair@286: /** ohair@286: *
ohair@286: * Maps a JavaBean property to XML IDREF. ohair@286: * ohair@286: *
ohair@286: * To preserve referential integrity of an object graph across XML ohair@286: * serialization followed by a XML deserialization, requires an object ohair@286: * reference to be marshalled by reference or containment ohair@286: * appropriately. Annotations @XmlID and @XmlIDREF ohair@286: * together allow a customized mapping of a JavaBean property's ohair@286: * type by containment or reference. ohair@286: * ohair@286: *
Usage
ohair@286: * The @XmlIDREF annotation can be used with the following ohair@286: * program elements: ohair@286: *See "Package Specification" in javax.xml.bind.package javadoc for ohair@286: * additional common information.
ohair@286: * ohair@286: *The usage is subject to the following constraints: ohair@286: *
Note: If the collection item type or the type of the ohair@286: * property (for non collection type) is java.lang.Object, then ohair@286: * the instance must contain a property/field annotated with ohair@286: * @XmlID attribute. ohair@286: *
Example: Map a JavaBean property to xs:IDREF ohair@286: * (i.e. by reference rather than by containment)
ohair@286: *ohair@286: * ohair@286: * //EXAMPLE: Code fragment ohair@286: * public class Shipping { ohair@286: * @XmlIDREF public Customer getCustomer(); ohair@286: * public void setCustomer(Customer customer); ohair@286: * .... ohair@286: * } ohair@286: * ohair@286: * <!-- Example: XML Schema fragment --> ohair@286: * <xs:complexType name="Shipping"> ohair@286: * <xs:complexContent> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="customer" type="xs:IDREF"/> ohair@286: * .... ohair@286: * </xs:sequence> ohair@286: * </xs:complexContent> ohair@286: * </xs:complexType> ohair@286: * ohair@286: *ohair@286: * ohair@286: * ohair@286: *
Example 2: The following is a complete example of ohair@286: * containment versus reference. ohair@286: * ohair@286: *
ohair@286: * // By default, Customer maps to complex type xs:Customer ohair@286: * public class Customer { ohair@286: * ohair@286: * // map JavaBean property type to xs:ID ohair@286: * @XmlID public String getCustomerID(); ohair@286: * public void setCustomerID(String id); ohair@286: * ohair@286: * // .... other properties not shown ohair@286: * } ohair@286: * ohair@286: * ohair@286: * // By default, Invoice maps to a complex type xs:Invoice ohair@286: * public class Invoice { ohair@286: * ohair@286: * // map by reference ohair@286: * @XmlIDREF public Customer getCustomer(); ohair@286: * public void setCustomer(Customer customer); ohair@286: * ohair@286: * // .... other properties not shown here ohair@286: * } ohair@286: * ohair@286: * // By default, Shipping maps to complex type xs:Shipping ohair@286: * public class Shipping { ohair@286: * ohair@286: * // map by reference ohair@286: * @XmlIDREF public Customer getCustomer(); ohair@286: * public void setCustomer(Customer customer); ohair@286: * } ohair@286: * ohair@286: * // at least one class must reference Customer by containment; ohair@286: * // Customer instances won't be marshalled. ohair@286: * @XmlElement(name="CustomerData") ohair@286: * public class CustomerData { ohair@286: * // map reference to Customer by containment by default. ohair@286: * public Customer getCustomer(); ohair@286: * ohair@286: * // maps reference to Shipping by containment by default. ohair@286: * public Shipping getShipping(); ohair@286: * ohair@286: * // maps reference to Invoice by containment by default. ohair@286: * public Invoice getInvoice(); ohair@286: * } ohair@286: * ohair@286: * <!-- XML Schema mapping for above code frament --> ohair@286: * ohair@286: * <xs:complexType name="Invoice"> ohair@286: * <xs:complexContent> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="customer" type="xs:IDREF"/> ohair@286: * .... ohair@286: * </xs:sequence> ohair@286: * </xs:complexContent> ohair@286: * </xs:complexType> ohair@286: * ohair@286: * <xs:complexType name="Shipping"> ohair@286: * <xs:complexContent> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="customer" type="xs:IDREF"/> ohair@286: * .... ohair@286: * </xs:sequence> ohair@286: * </xs:complexContent> ohair@286: * </xs:complexType> ohair@286: * ohair@286: * <xs:complexType name="Customer"> ohair@286: * <xs:complexContent> ohair@286: * <xs:sequence> ohair@286: * .... ohair@286: * </xs:sequence> ohair@286: * <xs:attribute name="CustomerID" type="xs:ID"/> ohair@286: * </xs:complexContent> ohair@286: * </xs:complexType> ohair@286: * ohair@286: * <xs:complexType name="CustomerData"> ohair@286: * <xs:complexContent> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="customer" type="xs:Customer"/> ohair@286: * <xs:element name="shipping" type="xs:Shipping"/> ohair@286: * <xs:element name="invoice" type="xs:Invoice"/> ohair@286: * </xs:sequence> ohair@286: * </xs:complexContent> ohair@286: * </xs:complexType> ohair@286: * ohair@286: * <xs:element name"customerData" type="xs:CustomerData"/> ohair@286: * ohair@286: * <!-- Instance document conforming to the above XML Schema --> ohair@286: * <customerData> ohair@286: * <customer customerID="Alice"> ohair@286: * .... ohair@286: * </customer> ohair@286: * ohair@286: * <shipping customer="Alice"> ohair@286: * .... ohair@286: * </shipping> ohair@286: * ohair@286: * <invoice customer="Alice"> ohair@286: * .... ohair@286: * </invoice> ohair@286: * </customerData> ohair@286: * ohair@286: *ohair@286: * ohair@286: *
Example 3: Mapping List to repeating element of type IDREF ohair@286: *
ohair@286: * // Code fragment ohair@286: * public class Shipping { ohair@286: * @XmlIDREF ohair@286: * @XmlElement(name="Alice") ohair@286: * public List customers; ohair@286: * } ohair@286: * ohair@286: * <!-- XML schema fragment --> ohair@286: * <xs:complexType name="Shipping"> ohair@286: * <xs:sequence> ohair@286: * <xs:choice minOccurs="0" maxOccurs="unbounded"> ohair@286: * <xs:element name="Alice" type="xs:IDREF"/> ohair@286: * </xs:choice> ohair@286: * </xs:sequence> ohair@286: * </xs:complexType> ohair@286: *ohair@286: * ohair@286: *
Example 4: Mapping a List to a list of elements of type IDREF. ohair@286: *
ohair@286: * //Code fragment ohair@286: * public class Shipping { ohair@286: * @XmlIDREF ohair@286: * @XmlElements( ohair@286: * @XmlElement(name="Alice", type="Customer.class") ohair@286: * @XmlElement(name="John", type="InternationalCustomer.class") ohair@286: * public List customers; ohair@286: * } ohair@286: * ohair@286: * <!-- XML Schema fragment --> ohair@286: * <xs:complexType name="Shipping"> ohair@286: * <xs:sequence> ohair@286: * <xs:choice minOccurs="0" maxOccurs="unbounded"> ohair@286: * <xs:element name="Alice" type="xs:IDREF"/> ohair@286: * <xs:element name="John" type="xs:IDREF"/> ohair@286: * </xs:choice> ohair@286: * </xs:sequence> ohair@286: * </xs:complexType> ohair@286: *ohair@286: * @author Sekhar Vajjhala, Sun Microsystems, Inc. ohair@286: * @see XmlID ohair@286: * @since JAXB2.0 ohair@286: */ ohair@286: ohair@286: @Retention(RUNTIME) @Target({FIELD, METHOD}) ohair@286: public @interface XmlIDREF {}