Mercurial > jdk8-mips64-public > jaxws / file comparison

comparison: src/share/jaxws_classes/javax/xml/bind/annotation/XmlElement.java

src/share/jaxws_classes/javax/xml/bind/annotation/XmlElement.java

changeset 0
373ffda63c9a
child 637
9c07ef4934dd
equal deleted inserted replaced
-1:000000000000 0:373ffda63c9a
1 /*
2 * Copyright (c) 2004, 2013, 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 * &#64;XmlElement(name="itemprice")
83 * public java.math.BigDecimal price;
84 * }
85 *
86 * &lt;!-- Example: Local XML Schema element -->
87 * &lt;xs:complexType name="USPrice"/>
88 * &lt;xs:sequence>
89 * &lt;xs:element name="itemprice" type="xs:decimal" minOccurs="0"/>
90 * &lt;/sequence>
91 * &lt;/xs:complexType>
92 * </pre>
93 * <p>
94 *
95 * <b> Example 2: </b> Map a field to a nillable element.
96 * <pre>
97 *
98 * //Example: Code fragment
99 * public class USPrice {
100 * &#64;XmlElement(nillable=true)
101 * public java.math.BigDecimal price;
102 * }
103 *
104 * &lt;!-- Example: Local XML Schema element -->
105 * &lt;xs:complexType name="USPrice">
106 * &lt;xs:sequence>
107 * &lt;xs:element name="price" type="xs:decimal" nillable="true" minOccurs="0"/>
108 * &lt;/sequence>
109 * &lt;/xs:complexType>
110 * </pre>
111 * <p>
112 * <b> Example 3: </b> Map a field to a nillable, required element.
113 * <pre>
114 *
115 * //Example: Code fragment
116 * public class USPrice {
117 * &#64;XmlElement(nillable=true, required=true)
118 * public java.math.BigDecimal price;
119 * }
120 *
121 * &lt;!-- Example: Local XML Schema element -->
122 * &lt;xs:complexType name="USPrice">
123 * &lt;xs:sequence>
124 * &lt;xs:element name="price" type="xs:decimal" nillable="true" minOccurs="1"/>
125 * &lt;/sequence>
126 * &lt;/xs:complexType>
127 * </pre>
128 * <p>
129 *
130 * <p> <b>Example 4: </b>Map a JavaBean property to an XML element
131 * with anonymous type.</p>
132 * <p>
133 * See Example 6 in @{@link XmlType}.
134 *
135 * <p>
136 * @author Sekhar Vajjhala, Sun Microsystems, Inc.
137 * @since JAXB2.0
138 */
139
140 @Retention(RUNTIME) @Target({FIELD, METHOD, PARAMETER})
141 public @interface XmlElement {
142 /**
143 * Name of the XML Schema element.
144 * <p> If the value is "##default", then element name is derived from the
145 * JavaBean property name.
146 */
147 String name() default "##default";
148
149 /**
150 * Customize the element declaration to be nillable.
151 * <p>If nillable() is true, then the JavaBean property is
152 * mapped to a XML Schema nillable element declaration.
153 */
154 boolean nillable() default false;
155
156 /**
157 * Customize the element declaration to be required.
158 * <p>If required() is true, then Javabean property is mapped to
159 * an XML schema element declaration with minOccurs="1".
160 * maxOccurs is "1" for a single valued property and "unbounded"
161 * for a multivalued property.
162 * <p>If required() is false, then the Javabean property is mapped
163 * to XML Schema element declaration with minOccurs="0".
164 * maxOccurs is "1" for a single valued property and "unbounded"
165 * for a multivalued property.
166 */
167
168 boolean required() default false;
169
170 /**
171 * XML target namespace of the XML Schema element.
172 * <p>
173 * If the value is "##default", then the namespace is determined
174 * as follows:
175 * <ol>
176 * <li>
177 * If the enclosing package has {@link XmlSchema} annotation,
178 * and its {@link XmlSchema#elementFormDefault() elementFormDefault}
179 * is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of
180 * the enclosing class.
181 *
182 * <li>
183 * Otherwise &#39;&#39; (which produces unqualified element in the default
184 * namespace.
185 * </ol>
186 */
187 String namespace() default "##default";
188
189 /**
190 * Default value of this element.
191 *
192 * <p>
193 * The <pre>'\u0000'</pre> value specified as a default of this annotation element
194 * is used as a poor-man's substitute for null to allow implementations
195 * to recognize the 'no default value' state.
196 */
197 String defaultValue() default "\u0000";
198
199 /**
200 * The Java class being referenced.
201 */
202 Class type() default DEFAULT.class;
203
204 /**
205 * Used in {@link XmlElement#type()} to
206 * signal that the type be inferred from the signature
207 * of the property.
208 */
209 static final class DEFAULT {}
210 }

Mercurial Repository: jdk8-mips64-public/jaxws

mercurial