XmlElement


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 javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
9   import java.lang.annotation.Retention  ;
10  import java.lang.annotation.Target  ;
11  
12  import static java.lang.annotation.ElementType  .*;
13  import static java.lang.annotation.RetentionPolicy  .*;
14  
15  /**
16   * Maps a JavaBean property to a XML element derived from property name.
17   *
18   * <p> <b>Usage</b> </p>
19   * <p>
20   * </tt>@XmlElement</tt> annotation can be used with the following program
21   * elements: 
22   * <ul> 
23   *   <li> a JavaBean property </li>
24   *   <li> non static, non transient field </li>
25   *   <li> within {@link XmlElements}
26   * <p>
27   *
28   * </ul>
29   * 
30   * The usage is subject to the following constraints:
31   * <ul> 
32   *   <li> This annotation can be used with following annotations:
33   *            {@link XmlID}, 
34   *            {@link XmlIDREF},
35   *            {@link XmlList},
36   *            {@link XmlSchemaType},
37   *            {@link XmlValue},
38   *            {@link XmlAttachmentRef},
39   *            {@link XmlMimeType},
40   *            {@link XmlInlineBinaryData},
41   *            {@link XmlElementWrapper},
42   *            {@link XmlJavaTypeAdapter}</li>
43   *   <li> if the type of JavaBean property is a collection type of
44   *        array, an indexed property, or a parameterized list, and
45   *        this annotation is used with {@link XmlElements} then,
46   *        <tt>@XmlElement.type()</tt> must be DEFAULT.class since the
47   *        collection item type is already known. </li>
48   * </ul>
49   *
50   * <p>
51   * A JavaBean property, when annotated with @XmlElement annotation
52   * is mapped to a local element in the XML Schema complex type to
53   * which the containing class is mapped.
54   *
55   * <p>
56   * <b>Example 1: </b> Map a public non static non final field to local
57   * element
58   * <pre>
59   *     //Example: Code fragment
60   *     public class USPrice {
61   *         &#64;XmlElement(name="itemprice")
62   *         public java.math.BigDecimal price;
63   *     }
64   *
65   *     &lt;!-- Example: Local XML Schema element -->
66   *     &lt;xs:complexType name="USPrice"/>
67   *       &lt;xs:sequence>
68   *         &lt;xs:element name="itemprice" type="xs:decimal" minOccurs="0"/>
69   *       &lt;/sequence>
70   *     &lt;/xs:complexType>
71   *   </pre>
72   * <p>
73   *
74   * <b> Example 2: </b> Map a field to a nillable element.
75   *   <pre>
76   *
77   *     //Example: Code fragment
78   *     public class USPrice {
79   *         &#64;XmlElement(nillable=true)
80   *         public java.math.BigDecimal price;
81   *     }
82   *
83   *     &lt;!-- Example: Local XML Schema element -->
84   *     &lt;xs:complexType name="USPrice">
85   *       &lt;xs:sequence>
86   *         &lt;xs:element name="price" type="xs:decimal" nillable="true" minOccurs="0"/>
87   *       &lt;/sequence>
88   *     &lt;/xs:complexType>
89   *   </pre>
90   * <p>
91   * <b> Example 3: </b> Map a field to a nillable, required element.
92   *   <pre>
93   *
94   *     //Example: Code fragment
95   *     public class USPrice {
96   *         &#64;XmlElement(nillable=true, required=true)
97   *         public java.math.BigDecimal price;
98   *     }
99   *
100  *     &lt;!-- Example: Local XML Schema element -->
101  *     &lt;xs:complexType name="USPrice">
102  *       &lt;xs:sequence>
103  *         &lt;xs:element name="price" type="xs:decimal" nillable="true" minOccurs="1"/>
104  *       &lt;/sequence>
105  *     &lt;/xs:complexType>
106  *   </pre>
107  * <p>
108  *
109  * <p> <b>Example 4: </b>Map a JavaBean property to an XML element
110  * with anonymous type.</p>
111  * <p>
112  * See Example 6 in @{@link XmlType}.
113  *
114  * <p>
115  * @author Sekhar Vajjhala, Sun Microsystems, Inc.
116  * @since JAXB2.0
117  * @version $Revision: 1.18 $
118  */
119 
120 @Retention  (RUNTIME) @Target  ({FIELD, METHOD})
121 public @interface XmlElement {
122     /**
123      * Name of the XML Schema element.
124      * <p> If the value is "##default", then element name is derived from the
125      * JavaBean property name. 
126      */
127     String   name() default "##default";
128  
129     /**
130      * Customize the element declaration to be nillable. 
131      * <p>If nillable() is true, then the JavaBean property is
132      * mapped to a XML Schema nillable element declaration. 
133      */
134     boolean nillable() default false;
135 
136     /**
137      * Customize the element declaration to be required.
138      * <p>If required() is true, then Javabean property is mapped to
139      * an XML schema element declaration with minOccurs="1". 
140      * maxOccurs is "1" for a single valued property and "unbounded"
141      * for a multivalued property.
142      * <p>If required() is false, then the Javabean property is mapped
143      * to XML Schema element declaration with minOccurs="0".
144      * maxOccurs is "1" for a single valued property and "unbounded"
145      * for a multivalued property.
146      */
147 
148     boolean required() default false;
149 
150     /**
151      * XML target namespace of the XML Schema element.
152      * <p>
153      * If the value is "##default", then the namespace is determined
154      * as follows:
155      * <ol>
156      *  <li>
157      *  If the enclosing package has {@link XmlSchema} annotation,
158      *  and its {@link XmlSchema#elementFormDefault() elementFormDefault}
159      *  is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of
160      *  the enclosing class.
161      *
162      *  <li>
163      *  Otherwise "" (which produces unqualified element in the default
164      *  namespace.
165      * </ol>
166      */
167     String   namespace() default "##default";
168 
169     /**
170      * Default value of this element.
171      *
172      * <p>
173      * The '' value specified as a default of this annotation element
174      * is used as a poor-man's substitute for null to allow implementations
175      * to recognize the 'no default value' state.  
176      */
177     String   defaultValue() default "\u0000";
178 
179     /**
180      * The Java class being referenced.
181      */
182     Class   type() default DEFAULT.class;
183 
184     /**
185      * Used in {@link XmlElement#type()} to
186      * signal that the type be inferred from the signature
187      * of the property.
188      */
189     static final class DEFAULT {}
190 }
191 
192 
193
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags