1 /*
2 * Copyright (c) 2004, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.bind.annotation;
27
28 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
29 import java.lang.annotation.Retention;
30 import java.lang.annotation.Target;
31
32 import static java.lang.annotation.ElementType.*;
33 import static java.lang.annotation.ElementType.PARAMETER;
34 import static java.lang.annotation.RetentionPolicy.*;
35
36 /**
37 * Maps a JavaBean property to a XML element derived from property name.
38 *
39 * <p> <b>Usage</b> </p>
40 * <p>
41 * <tt>@XmlElement</tt> annotation can be used with the following program
42 * elements:
43 * <ul>
44 * <li> a JavaBean property </li>
45 * <li> non static, non transient field </li>
46 * <li> within {@link XmlElements}
47 * <p>
48 *
49 * </ul>
50 *
51 * The usage is subject to the following constraints:
52 * <ul>
53 * <li> This annotation can be used with following annotations:
54 * {@link XmlID},
55 * {@link XmlIDREF},
56 * {@link XmlList},
57 * {@link XmlSchemaType},
58 * {@link XmlValue},
59 * {@link XmlAttachmentRef},
60 * {@link XmlMimeType},
61 * {@link XmlInlineBinaryData},
62 * {@link XmlElementWrapper},
63 * {@link XmlJavaTypeAdapter}</li>
64 * <li> if the type of JavaBean property is a collection type of
65 * array, an indexed property, or a parameterized list, and
66 * this annotation is used with {@link XmlElements} then,
67 * <tt>@XmlElement.type()</tt> must be DEFAULT.class since the
68 * collection item type is already known. </li>
69 * </ul>
70 *
71 * <p>
72 * A JavaBean property, when annotated with @XmlElement annotation
73 * is mapped to a local element in the XML Schema complex type to
74 * which the containing class is mapped.
75 *
76 * <p>
77 * <b>Example 1: </b> Map a public non static non final field to local
78 * element
79 * <pre>
80 * //Example: Code fragment
81 * public class USPrice {
82 * @XmlElement(name="itemprice")
83 * public java.math.BigDecimal price;
84 * }
85 * {@code
86 *
87 * <!-- Example: Local XML Schema element -->
88 * <xs:complexType name="USPrice"/>
89 * <xs:sequence>
90 * <xs:element name="itemprice" type="xs:decimal" minOccurs="0"/>
91 * </sequence>
92 * </xs:complexType>
93 * }</pre>
94 * <p>
95 *
96 * <b> Example 2: </b> Map a field to a nillable element.
97 * <pre>
98 *
99 * //Example: Code fragment
100 * public class USPrice {
101 * @XmlElement(nillable=true)
102 * public java.math.BigDecimal price;
103 * }
104 * {@code
105 *
106 * <!-- Example: Local XML Schema element -->
107 * <xs:complexType name="USPrice">
108 * <xs:sequence>
109 * <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="0"/>
110 * </sequence>
111 * </xs:complexType>
112 * }</pre>
113 * <p>
114 * <b> Example 3: </b> Map a field to a nillable, required element.
115 * <pre>
116 *
117 * //Example: Code fragment
118 * public class USPrice {
119 * @XmlElement(nillable=true, required=true)
120 * public java.math.BigDecimal price;
121 * }
122 * {@code
123 *
124 * <!-- Example: Local XML Schema element -->
125 * <xs:complexType name="USPrice">
126 * <xs:sequence>
127 * <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="1"/>
128 * </sequence>
129 * </xs:complexType>
130 * }</pre>
131 *
132 * <p> <b>Example 4: </b>Map a JavaBean property to an XML element
133 * with anonymous type.</p>
134 * <p>
135 * See Example 6 in @{@link XmlType}.
136 *
137 * <p>
138 * @author Sekhar Vajjhala, Sun Microsystems, Inc.
139 * @since 1.6, JAXB 2.0
140 */
141
142 @Retention(RUNTIME) @Target({FIELD, METHOD, PARAMETER})
143 public @interface XmlElement {
144 /**
145 * Name of the XML Schema element.
146 * <p> If the value is "##default", then element name is derived from the
147 * JavaBean property name.
148 */
149 String name() default "##default";
150
151 /**
152 * Customize the element declaration to be nillable.
153 * <p>If nillable() is true, then the JavaBean property is
154 * mapped to a XML Schema nillable element declaration.
155 */
156 boolean nillable() default false;
157
158 /**
159 * Customize the element declaration to be required.
160 * <p>If required() is true, then Javabean property is mapped to
161 * an XML schema element declaration with minOccurs="1".
162 * maxOccurs is "1" for a single valued property and "unbounded"
163 * for a multivalued property.
164 * <p>If required() is false, then the Javabean property is mapped
165 * to XML Schema element declaration with minOccurs="0".
166 * maxOccurs is "1" for a single valued property and "unbounded"
167 * for a multivalued property.
168 */
169
170 boolean required() default false;
171
172 /**
173 * XML target namespace of the XML Schema element.
174 * <p>
175 * If the value is "##default", then the namespace is determined
176 * as follows:
177 * <ol>
178 * <li>
179 * If the enclosing package has {@link XmlSchema} annotation,
180 * and its {@link XmlSchema#elementFormDefault() elementFormDefault}
181 * is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of
182 * the enclosing class.
183 *
184 * <li>
185 * Otherwise {@literal ''} (which produces unqualified element in the default
186 * namespace.
187 * </ol>
188 */
189 String namespace() default "##default";
190
191 /**
192 * Default value of this element.
193 *
194 * <p>
195 * The <pre>'\u0000'</pre> value specified as a default of this annotation element
196 * is used as a poor-man's substitute for null to allow implementations
197 * to recognize the 'no default value' state.
198 */
199 String defaultValue() default "\u0000";
200
201 /**
202 * The Java class being referenced.
203 */
204 Class type() default DEFAULT.class;
205
206 /**
207 * Used in {@link XmlElement#type()} to
208 * signal that the type be inferred from the signature
209 * of the property.
210 */
211 static final class DEFAULT {}
212 }