Source Code Cross Referenced for XmlID.java in  » 6.0-JDK-Modules » jaxb-api » javax » xml » bind » annotation » Java Source Code / Java DocumentationJava Source Code and Java Documentation

01:        /*
02:         * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
03:         * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
04:         */
05:
06:        package javax.xml.bind.annotation;
07:
08:        import java.lang.annotation.Target;
09:        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 ID.
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;XmlID</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:         * The usage is subject to the following constraints:
37:         * <ul> 
38:         *   <li> At most one field or property in a class can be annotated
39:         *        with <tt>&#64;XmlID</tt>.  </li>
40:         *   <li> The JavaBean property's type must be <tt>java.lang.String</tt>.</li>
41:         *   <li> The only other mapping annotations that can be used
42:         *        with <tt>&#64;XmlID</tt>
43:         *        are:<tt>&#64;XmlElement</tt> and <tt>&#64;XmlAttribute</tt>.</li>  
44:         * </ul>
45:         * 
46:         * <p><b>Example</b>: Map a JavaBean property's type to <tt>xs:ID</tt></p>
47:         * <pre>
48:         *    // Example: code fragment
49:         *    public class Customer {
50:         *        &#64;XmlAttribute
51:         *        &#64;XmlID
52:         *        public String getCustomerID();
53:         *        public void setCustomerID(String id);
54:         *        .... other properties not shown 
55:         *    }
56:         *
57:         *    &lt;!-- Example: XML Schema fragment -->
58:         *    &lt;xs:complexType name="Customer">
59:         *      &lt;xs:complexContent>
60:         *        &lt;xs:sequence>
61:         *          ....
62:         *        &lt;/xs:sequence>
63:         *        &lt;xs:attribute name="customerID" type="xs:ID"/>
64:         *      &lt;/xs:complexContent>
65:         *    &lt;/xs:complexType>
66:         * </pre>
67:         *
68:         * @author Sekhar Vajjhala, Sun Microsystems, Inc.
69:         * @see XmlIDREF
70:         * @since JAXB2.0
71:         * @version $Revision: 1.5 $
72:         */
73:
74:        @Retention(RUNTIME)
75:        @Target({FIELD,METHOD})
76:        public @interface XmlID {
77:        }