/* * Copyright (c) 2004, 2015, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.xml.bind.annotation; import java.lang.annotation.Target; import java.lang.annotation.Retention; import static java.lang.annotation.ElementType.*; import static java.lang.annotation.RetentionPolicy.*; /** *

* Maps a JavaBean property to XML IDREF. * *

* To preserve referential integrity of an object graph across XML * serialization followed by a XML deserialization, requires an object * reference to be marshaled by reference or containment * appropriately. Annotations {@code @XmlID} and {@code @XmlIDREF} * together allow a customized mapping of a JavaBean property's * type by containment or reference. * *

Usage

* The {@code @XmlIDREF} annotation can be used with the following * program elements: * * *

See "Package Specification" in javax.xml.bind.package javadoc for * additional common information.

* *

The usage is subject to the following constraints: *

*

Example: Map a JavaBean property to {@code xs:IDREF} * (i.e. by reference rather than by containment)

* 
 *
 *   //EXAMPLE: Code fragment
 *   public class Shipping {
 *       @XmlIDREF public Customer getCustomer();
 *       public void setCustomer(Customer customer);
 *       ....
 *    }
 * {@code
 *
 *   
 *   
 *     
 *       
 *         
 *         ....
 *       
 *     
 *   
 *
 * }
* * *

Example 2: The following is a complete example of * containment versus reference. * * 

 *    // By default, Customer maps to complex type {@code xs:Customer}
 *    public class Customer {
 *
 *        // map JavaBean property type to {@code xs:ID}
 *        @XmlID public String getCustomerID();
 *        public void setCustomerID(String id);
 *
 *        // .... other properties not shown
 *    }
 *
 *
 *   // By default, Invoice maps to a complex type {@code xs:Invoice}
 *   public class Invoice {
 *
 *       // map by reference
 *       @XmlIDREF public Customer getCustomer();
 *       public void setCustomer(Customer customer);
 *
 *      // .... other properties not shown here
 *   }
 *
 *   // By default, Shipping maps to complex type {@code xs:Shipping}
 *   public class Shipping {
 *
 *       // map by reference
 *       @XmlIDREF public Customer getCustomer();
 *       public void setCustomer(Customer customer);
 *   }
 *
 *   // at least one class must reference Customer by containment;
 *   // Customer instances won't be marshalled.
 *   @XmlElement(name="CustomerData")
 *   public class CustomerData {
 *       // map reference to Customer by containment by default.
 *       public Customer getCustomer();
 *
 *       // maps reference to Shipping by containment by default.
 *       public Shipping getShipping();
 *
 *       // maps reference to Invoice by containment by default.
 *       public Invoice getInvoice();
 *   }
 * {@code
 *
 *   
 *
 *   
 *     
 *       
 *         
 *         ....
 *       
 *     
 *   
 *
 *   
 *     
 *       
 *         
 *         ....
 *       
 *     
 *   
 *
 *   
 *     
 *       
 *         ....
 *       
 *       
 *     
 *   
 *
 *   
 *     
 *       
 *         
 *         
 *         
 *       
 *     
 *   
 *
 *   
 *
 *   
 *    
 *       
 *           ....
 *       
 *
 *       
 *           ....
 *       
 *
 *       
 *           ....
 *       
 *   
 *
 * }
* *

Example 3: Mapping List to repeating element of type IDREF * 

 *     // Code fragment
 *     public class Shipping {
 *         @XmlIDREF
 *         @XmlElement(name="Alice")
 *             public List customers;
 *     }
 * {@code
 *
 *     
 *     
 *       
 *         
 *           
 *         
 *       
 *     
 * }
* *

Example 4: Mapping a List to a list of elements of type IDREF. * 

 *     //Code fragment
 *     public class Shipping {
 *         @XmlIDREF
 *         @XmlElements(
 *             @XmlElement(name="Alice", type="Customer.class")
 *              @XmlElement(name="John", type="InternationalCustomer.class")
 *         public List customers;
 *     }
 * {@code
 *
 *     
 *     
 *       
 *         
 *           
 *           
 *         
 *       
 *     
 * }
* @author Sekhar Vajjhala, Sun Microsystems, Inc. * @see XmlID * @since 1.6, JAXB 2.0 */ @Retention(RUNTIME) @Target({FIELD, METHOD}) public @interface XmlIDREF {}