XmlIDREF


1   /*
2    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
3    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4    */
5   
6   package javax.xml.bind.annotation;
7   
8   import java.lang.annotation.Target  ;
9   import java.lang.annotation.Retention  ;
10  import static java.lang.annotation.ElementType  .*;
11  import static java.lang.annotation.RetentionPolicy  .*;
12  
13  /**
14   * <p>
15   * Maps a JavaBean property to XML IDREF.
16   * 
17   * <p>
18   * To preserve referential integrity of an object graph across XML
19   * serialization followed by a XML deserialization, requires an object
20   * reference to be marshalled by reference or containment
21   * appropriately. Annotations <tt>&#64;XmlID</tt> and <tt>&#64;XmlIDREF</tt>
22   * together allow a customized mapping of a JavaBean property's
23   * type by containment or reference. 
24   *
25   * <p><b>Usage</b> </p>
26   * The <tt>&#64;XmlIDREF</tt> annotation can be used with the following
27   * program elements: 
28   * <ul> 
29   *   <li> a JavaBean property </li>
30   *   <li> non static, non transient field </li>
31   * </ul>
32   * 
33   * <p>See "Package Specification" in javax.xml.bind.package javadoc for
34   * additional common information.</p>
35   *
36   * <p> The usage is subject to the following constraints:
37   * <ul>
38   *
39   *   <li> If the type of the field or property is a collection type,
40   *        then the collection item type must contain a property or
41   *        field annotated with <tt>&#64;XmlID</tt>.  </li> 
42   *   <li> If the field or property is single valued, then the type of
43   *        the property or field must contain a property or field
44   *        annotated with <tt>&#64;XmlID</tt>.
45   *        <p>Note: If the collection item type or the type of the
46   *        property (for non collection type) is java.lang.Object, then
47   *        the instance must contain a property/field annotated with
48   *        <tt>&#64;XmlID</tt> attribute.  
49   *        </li>
50   *   <li> This annotation can be used with the following annotations:
51   *        {@link XmlElement}, {@link XmlAttribute}, {@link XmlList}, 
52   *        and {@link XmlElements}.</li>  
53   *
54   * </ul>
55   * <p><b>Example:</b> Map a JavaBean property to <tt>xs:IDREF</tt>
56   *   (i.e. by reference rather than by containment)</p>
57   * <pre>
58   *
59   *   //EXAMPLE: Code fragment
60   *   public class Shipping {
61   *       &#64;XmlIDREF public Customer getCustomer();
62   *       public void setCustomer(Customer customer);
63   *       ....
64   *    }
65   *
66   *   &lt;!-- Example: XML Schema fragment -->
67   *   &lt;xs:complexType name="Shipping">
68   *     &lt;xs:complexContent>
69   *       &lt;xs:sequence>
70   *         &lt;xs:element name="customer" type="xs:IDREF"/>
71   *         ....
72   *       &lt;/xs:sequence>
73   *     &lt;/xs:complexContent>
74   *   &lt;/xs:complexType>
75   *
76   * </pre>
77   *
78   *
79   * <p><b>Example 2: </b> The following is a complete example of
80   * containment versus reference.
81   * 
82   * <pre>
83   *    // By default, Customer maps to complex type <tt>xs:Customer</tt>
84   *    public class Customer {
85   *        
86   *        // map JavaBean property type to <tt>xs:ID</tt>
87   *        &#64;XmlID public String getCustomerID();
88   *        public void setCustomerID(String id);
89   *
90   *        // .... other properties not shown 
91   *    }
92   *
93   *
94   *   // By default, Invoice maps to a complex type <tt>xs:Invoice</tt> 
95   *   public class Invoice {
96   *    
97   *       // map by reference
98   *       &#64;XmlIDREF public Customer getCustomer();       
99   *       public void setCustomer(Customer customer);
100  *
101  *      // .... other properties not shown here
102  *   }
103  *
104  *   // By default, Shipping maps to complex type <tt>xs:Shipping</tt>
105  *   public class Shipping {
106  *
107  *       // map by reference
108  *       &#64;XmlIDREF public Customer getCustomer();       
109  *       public void setCustomer(Customer customer);
110  *   }
111  *
112  *   // at least one class must reference Customer by containment;
113  *   // Customer instances won't be marshalled.
114  *   &#64;XmlElement(name="CustomerData")
115  *   public class CustomerData {
116  *       // map reference to Customer by containment by default.
117  *       public Customer getCustomer();
118  *
119  *       // maps reference to Shipping by containment by default. 
120  *       public Shipping getShipping();     
121  *
122  *       // maps reference to Invoice by containment by default. 
123  *       public Invoice getInvoice();     
124  *   }
125  *
126  *   &lt;!-- XML Schema mapping for above code frament -->
127  *
128  *   &lt;xs:complexType name="Invoice">
129  *     &lt;xs:complexContent>
130  *       &lt;xs:sequence>
131  *         &lt;xs:element name="customer" type="xs:IDREF"/>
132  *         ....
133  *       &lt;/xs:sequence>
134  *     &lt;/xs:complexContent>
135  *   &lt;/xs:complexType>
136  *
137  *   &lt;xs:complexType name="Shipping">
138  *     &lt;xs:complexContent>
139  *       &lt;xs:sequence>
140  *         &lt;xs:element name="customer" type="xs:IDREF"/>
141  *         ....
142  *       &lt;/xs:sequence>
143  *     &lt;/xs:complexContent>
144  *   &lt;/xs:complexType>
145  *
146  *   &lt;xs:complexType name="Customer">
147  *     &lt;xs:complexContent>
148  *       &lt;xs:sequence>
149  *         ....
150  *       &lt;/xs:sequence>
151  *       &lt;xs:attribute name="CustomerID" type="xs:ID"/>
152  *     &lt;/xs:complexContent>
153  *   &lt;/xs:complexType>
154  *
155  *   &lt;xs:complexType name="CustomerData">
156  *     &lt;xs:complexContent>
157  *       &lt;xs:sequence>
158  *         &lt;xs:element name="customer" type="xs:Customer"/>
159  *         &lt;xs:element name="shipping" type="xs:Shipping"/>
160  *         &lt;xs:element name="invoice"  type="xs:Invoice"/>
161  *       &lt;/xs:sequence>
162  *     &lt;/xs:complexContent>
163  *   &lt;/xs:complexType>
164  *
165  *   &lt;xs:element name"customerData" type="xs:CustomerData"/>
166  *
167  *   &lt;!-- Instance document conforming to the above XML Schema -->
168  *    &lt;customerData>
169  *       &lt;customer customerID="Alice">
170  *           ....
171  *       &lt;/customer>
172  *
173  *       &lt;shipping customer="Alice">
174  *           ....
175  *       &lt;/shipping>
176  *         
177  *       &lt;invoice customer="Alice">
178  *           ....
179  *       &lt;/invoice>
180  *   &lt;/customerData>
181  *
182  * </pre>
183  *
184  * <p><b>Example 3: </b> Mapping List to repeating element of type IDREF
185  * <pre>
186  *     // Code fragment
187  *     public class Shipping {
188  *         &#64;XmlIDREF
189  *         &#64;XmlElement(name="Alice")
190  *             public List customers;
191  *     }
192  *
193  *     &lt;!-- XML schema fragment -->
194  *     &lt;xs:complexType name="Shipping">
195  *       &lt;xs:sequence>
196  *         &lt;xs:choice minOccurs="0" maxOccurs="unbounded">
197  *           &lt;xs:element name="Alice" type="xs:IDREF"/>
198  *         &lt;/xs:choice>
199  *       &lt;/xs:sequence>
200  *     &lt;/xs:complexType> 
201  * </pre>
202  *
203  * <p><b>Example 4: </b> Mapping a List to a list of elements of type IDREF.
204  * <pre>
205  *     //Code fragment
206  *     public class Shipping {
207  *         &#64;XmlIDREF
208  *         &#64;XmlElements(
209  *             &#64;XmlElement(name="Alice", type="Customer.class")
210  *              &#64;XmlElement(name="John", type="InternationalCustomer.class")
211  *         public List customers;
212  *     }
213  *
214  *     &lt;!-- XML Schema fragment -->
215  *     &lt;xs:complexType name="Shipping">
216  *       &lt;xs:sequence>
217  *         &lt;xs:choice minOccurs="0" maxOccurs="unbounded">
218  *           &lt;xs:element name="Alice" type="xs:IDREF"/>
219  *           &lt;xs:element name="John" type="xs:IDREF"/>
220  *         &lt;/xs:choice>
221  *       &lt;/xs:sequence>
222  *     &lt;/xs:complexType> 
223  * </pre>
224  * @author Sekhar Vajjhala, Sun Microsystems, Inc. 
225  * @see XmlID
226  * @since JAXB2.0
227  * @version $Revision: 1.11 $
228  */
229 
230 @Retention  (RUNTIME) @Target  ({FIELD, METHOD})
231 public @interface XmlIDREF {}
232
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags