001: /*
002: * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.bind.annotation;
007:
008: import java.lang.annotation.Target;
009: import java.lang.annotation.Retention;
010: import static java.lang.annotation.ElementType.*;
011: import static java.lang.annotation.RetentionPolicy.*;
012:
013: /**
014: * <p>
015: * Maps a JavaBean property to XML IDREF.
016: *
017: * <p>
018: * To preserve referential integrity of an object graph across XML
019: * serialization followed by a XML deserialization, requires an object
020: * reference to be marshalled by reference or containment
021: * appropriately. Annotations <tt>@XmlID</tt> and <tt>@XmlIDREF</tt>
022: * together allow a customized mapping of a JavaBean property's
023: * type by containment or reference.
024: *
025: * <p><b>Usage</b> </p>
026: * The <tt>@XmlIDREF</tt> annotation can be used with the following
027: * program elements:
028: * <ul>
029: * <li> a JavaBean property </li>
030: * <li> non static, non transient field </li>
031: * </ul>
032: *
033: * <p>See "Package Specification" in javax.xml.bind.package javadoc for
034: * additional common information.</p>
035: *
036: * <p> The usage is subject to the following constraints:
037: * <ul>
038: *
039: * <li> If the type of the field or property is a collection type,
040: * then the collection item type must contain a property or
041: * field annotated with <tt>@XmlID</tt>. </li>
042: * <li> If the field or property is single valued, then the type of
043: * the property or field must contain a property or field
044: * annotated with <tt>@XmlID</tt>.
045: * <p>Note: If the collection item type or the type of the
046: * property (for non collection type) is java.lang.Object, then
047: * the instance must contain a property/field annotated with
048: * <tt>@XmlID</tt> attribute.
049: * </li>
050: * <li> This annotation can be used with the following annotations:
051: * {@link XmlElement}, {@link XmlAttribute}, {@link XmlList},
052: * and {@link XmlElements}.</li>
053: *
054: * </ul>
055: * <p><b>Example:</b> Map a JavaBean property to <tt>xs:IDREF</tt>
056: * (i.e. by reference rather than by containment)</p>
057: * <pre>
058: *
059: * //EXAMPLE: Code fragment
060: * public class Shipping {
061: * @XmlIDREF public Customer getCustomer();
062: * public void setCustomer(Customer customer);
063: * ....
064: * }
065: *
066: * <!-- Example: XML Schema fragment -->
067: * <xs:complexType name="Shipping">
068: * <xs:complexContent>
069: * <xs:sequence>
070: * <xs:element name="customer" type="xs:IDREF"/>
071: * ....
072: * </xs:sequence>
073: * </xs:complexContent>
074: * </xs:complexType>
075: *
076: * </pre>
077: *
078: *
079: * <p><b>Example 2: </b> The following is a complete example of
080: * containment versus reference.
081: *
082: * <pre>
083: * // By default, Customer maps to complex type <tt>xs:Customer</tt>
084: * public class Customer {
085: *
086: * // map JavaBean property type to <tt>xs:ID</tt>
087: * @XmlID public String getCustomerID();
088: * public void setCustomerID(String id);
089: *
090: * // .... other properties not shown
091: * }
092: *
093: *
094: * // By default, Invoice maps to a complex type <tt>xs:Invoice</tt>
095: * public class Invoice {
096: *
097: * // map by reference
098: * @XmlIDREF public Customer getCustomer();
099: * 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: * @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: * @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: * <!-- XML Schema mapping for above code frament -->
127: *
128: * <xs:complexType name="Invoice">
129: * <xs:complexContent>
130: * <xs:sequence>
131: * <xs:element name="customer" type="xs:IDREF"/>
132: * ....
133: * </xs:sequence>
134: * </xs:complexContent>
135: * </xs:complexType>
136: *
137: * <xs:complexType name="Shipping">
138: * <xs:complexContent>
139: * <xs:sequence>
140: * <xs:element name="customer" type="xs:IDREF"/>
141: * ....
142: * </xs:sequence>
143: * </xs:complexContent>
144: * </xs:complexType>
145: *
146: * <xs:complexType name="Customer">
147: * <xs:complexContent>
148: * <xs:sequence>
149: * ....
150: * </xs:sequence>
151: * <xs:attribute name="CustomerID" type="xs:ID"/>
152: * </xs:complexContent>
153: * </xs:complexType>
154: *
155: * <xs:complexType name="CustomerData">
156: * <xs:complexContent>
157: * <xs:sequence>
158: * <xs:element name="customer" type="xs:Customer"/>
159: * <xs:element name="shipping" type="xs:Shipping"/>
160: * <xs:element name="invoice" type="xs:Invoice"/>
161: * </xs:sequence>
162: * </xs:complexContent>
163: * </xs:complexType>
164: *
165: * <xs:element name"customerData" type="xs:CustomerData"/>
166: *
167: * <!-- Instance document conforming to the above XML Schema -->
168: * <customerData>
169: * <customer customerID="Alice">
170: * ....
171: * </customer>
172: *
173: * <shipping customer="Alice">
174: * ....
175: * </shipping>
176: *
177: * <invoice customer="Alice">
178: * ....
179: * </invoice>
180: * </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: * @XmlIDREF
189: * @XmlElement(name="Alice")
190: * public List customers;
191: * }
192: *
193: * <!-- XML schema fragment -->
194: * <xs:complexType name="Shipping">
195: * <xs:sequence>
196: * <xs:choice minOccurs="0" maxOccurs="unbounded">
197: * <xs:element name="Alice" type="xs:IDREF"/>
198: * </xs:choice>
199: * </xs:sequence>
200: * </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: * @XmlIDREF
208: * @XmlElements(
209: * @XmlElement(name="Alice", type="Customer.class")
210: * @XmlElement(name="John", type="InternationalCustomer.class")
211: * public List customers;
212: * }
213: *
214: * <!-- XML Schema fragment -->
215: * <xs:complexType name="Shipping">
216: * <xs:sequence>
217: * <xs:choice minOccurs="0" maxOccurs="unbounded">
218: * <xs:element name="Alice" type="xs:IDREF"/>
219: * <xs:element name="John" type="xs:IDREF"/>
220: * </xs:choice>
221: * </xs:sequence>
222: * </xs:complexType>
223: * </pre>
224: * @author Sekhar Vajjhala, Sun Microsystems, Inc.
225: * @see XmlID
226: * @since JAXB2.0
227: * @version $Revision: 1.12 $
228: */
229:
230: @Retention(RUNTIME)
231: @Target({FIELD,METHOD})
232: public @interface XmlIDREF {
233: }
|