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.Retention;
009: import java.lang.annotation.Target;
010:
011: import static java.lang.annotation.RetentionPolicy.RUNTIME;
012: import static java.lang.annotation.ElementType.TYPE;
013:
014: /**
015: * Maps a class or an enum type to an XML element.
016: *
017: * <p> <b>Usage</b> </p>
018: * <p>
019: * The @XmlRootElement annotation can be used with the following program
020: * elements:
021: * <ul>
022: * <li> a top level class </li>
023: * <li> an enum type </li>
024: * </ul>
025: *
026: * <p>See "Package Specification" in javax.xml.bind.package javadoc for
027: * additional common information.</p>
028: *
029: * <p>
030: * When a top level class or an enum type is annotated with the
031: * @XmlRootElement annotation, then its value is represented
032: * as XML element in an XML document.
033: *
034: * <p> This annotation can be used with the following annotations:
035: * {@link XmlType}, {@link XmlEnum}, {@link XmlAccessorType},
036: * {@link XmlAccessorOrder}.
037: * <p>
038:
039: * <p>
040: * <b>Example 1: </b> Associate an element with XML Schema type
041: * <pre>
042: * // Example: Code fragment
043: * @XmlRootElement
044: * class Point {
045: * int x;
046: * int y;
047: * Point(int _x,int _y) {x=_x;y=_y;}
048: * }
049: * </pre>
050: *
051: * <pre>
052: * //Example: Code fragment corresponding to XML output
053: * marshal( new Point(3,5), System.out);
054: * </pre>
055: *
056: * <pre><xmp>
057: * <!-- Example: XML output -->
058: * <point>
059: * <x> 3 </x>
060: * <y> 5 </y>
061: * </point>
062: * </xmp></pre>
063: *
064: * The annotation causes an global element declaration to be produced
065: * in the schema. The global element declaration is associated with
066: * the XML schema type to which the class is mapped.
067: *
068: * <pre><xmp>
069: * <!-- Example: XML schema definition -->
070: * <xs:element name="point" type="point"/>
071: * <xs:complexType name="point">
072: * <xs:sequence>
073: * <xs:element name="x" type="xs:int"/>
074: * <xs:element name="y" type="xs:int"/>
075: * </xs:sequence>
076: * </xs:complexType>
077: * </xmp></pre>
078: *
079: * <p>
080: *
081: * <b>Example 2: Orthogonality to type inheritance </b>
082: *
083: * <p>
084: * An element declaration annotated on a type is not inherited by its
085: * derived types. The following example shows this.
086: * <pre>
087: * // Example: Code fragment
088: * @XmlRootElement
089: * class Point3D extends Point {
090: * int z;
091: * Point3D(int _x,int _y,int _z) {super(_x,_y);z=_z;}
092: * }
093: *
094: * //Example: Code fragment corresponding to XML output *
095: * marshal( new Point3D(3,5,0), System.out );
096: *
097: * <!-- Example: XML output -->
098: * <!-- The element name is point3D not point -->
099: * <point3D>
100: * <x>3</x>
101: * <y>5</y>
102: * <z>0</z>
103: * </point3D>
104: *
105: * <!-- Example: XML schema definition -->
106: * <xs:element name="point3D" type="point3D"/>
107: * <xs:complexType name="point3D">
108: * <xs:complexContent>
109: * <xs:extension base="point">
110: * <xs:sequence>
111: * <xs:element name="z" type="xs:int"/>
112: * </xs:sequence>
113: * </xs:extension>
114: * </xs:complexContent>
115: * </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: * @XmlRootElement(name="PriceElement")
123: * public class USPrice {
124: * @XmlElement
125: * public java.math.BigDecimal price;
126: * }
127: *
128: * <!-- Example: XML schema definition -->
129: * <xs:element name="PriceElement" type="USPrice"/>
130: * <xs:complexType name="USPrice">
131: * <xs:sequence>
132: * <xs:element name="price" type="xs:decimal"/>
133: * </sequence>
134: * </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: }
|