XmlRootElement


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.Retention  ;
9   import java.lang.annotation.Target  ;
10  
11  import static java.lang.annotation.RetentionPolicy.RUNTIME  ;
12  import static java.lang.annotation.ElementType.TYPE  ;
13  
14  /**
15   * Maps a class or an enum type to an XML element.
16   *
17   * <p> <b>Usage</b> </p>
18   * <p>
19   * The &#64;XmlRootElement annotation can be used with the following program
20   * elements: 
21   * <ul> 
22   *   <li> a top level class </li>
23   *   <li> an enum type </li>
24   * </ul>
25   *
26   * <p>See "Package Specification" in javax.xml.bind.package javadoc for
27   * additional common information.</p>
28   * 
29   * <p>
30   * When a top level class or an enum type is annotated with the 
31   * &#64;XmlRootElement annotation, then its value is represented 
32   * as XML element in an XML document.
33   *
34   * <p> This annotation can be used with the following annotations:
35   * {@link XmlType}, {@link XmlEnum}, {@link XmlAccessorType}, 
36   * {@link XmlAccessorOrder}.
37   * <p>
38  
39   * <p>
40   * <b>Example 1: </b> Associate an element with XML Schema type
41   * <pre>
42   *     // Example: Code fragment
43   *     &#64;XmlRootElement
44   *     class Point {
45   *        int x;
46   *        int y;
47   *        Point(int _x,int _y) {x=_x;y=_y;}
48   *     }
49   * </pre>
50   *
51   * <pre>
52   *     //Example: Code fragment corresponding to XML output
53   *     marshal( new Point(3,5), System.out);
54   * </pre>
55   *
56   * <pre><xmp>
57   *     <!-- Example: XML output -->
58   *     <point>
59   *       <x> 3 </x>
60   *       <y> 5 </y>
61   *     </point>
62   * </xmp></pre>
63   *
64   * The annotation causes an global element declaration to be produced
65   * in the schema. The global element declaration is associated with
66   * the XML schema type to which the class is mapped.
67   *
68   * <pre><xmp>
69   *     <!-- Example: XML schema definition -->
70   *     <xs:element name="point" type="point"/>
71   *     <xs:complexType name="point">
72   *       <xs:sequence>
73   *         <xs:element name="x" type="xs:int"/>
74   *         <xs:element name="y" type="xs:int"/>
75   *       </xs:sequence>
76   *     </xs:complexType>
77   * </xmp></pre>
78   *
79   * <p>
80   *
81   * <b>Example 2: Orthogonality to type inheritance </b>
82   * 
83   * <p>
84   * An element declaration annotated on a type is not inherited by its
85   * derived types. The following example shows this.
86   * <pre>
87   *     // Example: Code fragment
88   *     &#64;XmlRootElement
89   *     class Point3D extends Point {
90   *         int z;
91   *         Point3D(int _x,int _y,int _z) {super(_x,_y);z=_z;}
92   *     }
93   *
94   *     //Example: Code fragment corresponding to XML output * 
95   *     marshal( new Point3D(3,5,0), System.out );
96   *
97   *     &lt;!-- Example: XML output -->
98   *     &lt;!-- The element name is point3D not point -->
99   *     &lt;point3D>
100  *       &lt;x>3&lt;/x>
101  *       &lt;y>5&lt;/y>
102  *       &lt;z>0&lt;/z>
103  *     &lt;/point3D>
104  *
105  *     &lt;!-- Example: XML schema definition -->
106  *     &lt;xs:element name="point3D" type="point3D"/>
107  *     &lt;xs:complexType name="point3D">
108  *       &lt;xs:complexContent>
109  *         &lt;xs:extension base="point">
110  *           &lt;xs:sequence>
111  *             &lt;xs:element name="z" type="xs:int"/>
112  *           &lt;/xs:sequence>
113  *         &lt;/xs:extension>
114  *       &lt;/xs:complexContent>
115  *     &lt;/xs:complexType>
116  * </pre>
117  *
118  * <b>Example 3: </b> Associate a global element with XML Schema type
119  * to which the class is mapped.
120  * <pre>
121  *     //Example: Code fragment
122  *     &#64;XmlRootElement(name="PriceElement")
123  *     public class USPrice {
124  *         &#64;XmlElement
125  *         public java.math.BigDecimal price;
126  *     }
127  *
128  *     &lt;!-- Example: XML schema definition -->
129  *     &lt;xs:element name="PriceElement" type="USPrice"/>
130  *     &lt;xs:complexType name="USPrice">
131  *       &lt;xs:sequence>
132  *         &lt;xs:element name="price" type="xs:decimal"/>
133  *       &lt;/sequence>
134  *     &lt;/xs:complexType>
135  * </pre>
136  *
137  * @author Sekhar Vajjhala, Sun Microsystems, Inc.
138  * @since JAXB2.0
139  */
140 @Retention  (RUNTIME)
141 @Target  ({TYPE})
142 public @interface XmlRootElement {
143     /**
144      * namespace name of the XML element.
145      * <p>
146      * If the value is "##default", then the XML namespace name is derived
147      * from the package of the class ( {@link XmlSchema} ). If the
148      * package is unnamed, then the XML namespace is the default empty
149      * namespace.
150      */
151     String   namespace() default "##default";
152 
153     /**
154      * local name of the XML element.
155      * <p>
156      * If the value is "##default", then the name is derived from the
157      * class name. 
158      *
159      */
160     String   name() default "##default";
161 
162 }
163
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags