1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/jaxws_classes/javax/xml/bind/annotation/XmlType.java Wed Apr 27 01:27:09 2016 +0800
1.3 @@ -0,0 +1,452 @@
1.4 +/*
1.5 + * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package javax.xml.bind.annotation;
1.30 +
1.31 +import static java.lang.annotation.ElementType.TYPE;
1.32 +import java.lang.annotation.Retention;
1.33 +import static java.lang.annotation.RetentionPolicy.RUNTIME;
1.34 +import java.lang.annotation.Target;
1.35 +
1.36 +/**
1.37 + * <p>
1.38 + * Maps a class or an enum type to a XML Schema type.
1.39 + *
1.40 + * <p><b>Usage</b></p>
1.41 + * <p> The <tt>@XmlType</tt> annnotation can be used with the following program
1.42 + * elements:
1.43 + * <ul>
1.44 + * <li> a top level class </li>
1.45 + * <li> an enum type </li>
1.46 + * </ul>
1.47 + *
1.48 + * <p>See "Package Specification" in javax.xml.bind.package javadoc for
1.49 + * additional common information.</p>
1.50 + *
1.51 + * <h3> Mapping a Class </h3>
1.52 + * <p>
1.53 + * A class maps to a XML Schema type. A class is a data container for
1.54 + * values represented by properties and fields. A schema type is a
1.55 + * data container for values represented by schema components within a
1.56 + * schema type's content model (e.g. model groups, attributes etc).
1.57 + * <p> To be mapped, a class must either have a public no-arg
1.58 + * constructor or a static no-arg factory method. The static factory
1.59 + * method can be specified in <tt>factoryMethod()</tt> and
1.60 + * <tt>factoryClass()</tt> annotation elements. The static factory
1.61 + * method or the no-arg constructor is used during unmarshalling to
1.62 + * create an instance of this class. If both are present, the static
1.63 + * factory method overrides the no-arg constructor.
1.64 + * <p>
1.65 + * A class maps to either a XML Schema complex type or a XML Schema simple
1.66 + * type. The XML Schema type is derived based on the
1.67 + * mapping of JavaBean properties and fields contained within the
1.68 + * class. The schema type to which the class is mapped can either be
1.69 + * named or anonymous. A class can be mapped to an anonymous schema
1.70 + * type by annotating the class with <tt>@XmlType(name="")</tt>.
1.71 + * <p>
1.72 + * Either a global element, local element or a local attribute can be
1.73 + * associated with an anonymous type as follows:
1.74 + * <ul>
1.75 + * <li><b>global element: </b> A global element of an anonymous
1.76 + * type can be derived by annotating the class with @{@link
1.77 + * XmlRootElement}. See Example 3 below. </li>
1.78 + *
1.79 + * <li><b>local element: </b> A JavaBean property that references
1.80 + * a class annotated with @XmlType(name="") and is mapped to the
1.81 + * element associated with the anonymous type. See Example 4
1.82 + * below.</li>
1.83 + *
1.84 + * <li><b>attribute: </b> A JavaBean property that references
1.85 + * a class annotated with @XmlType(name="") and is mapped to the
1.86 + * attribute associated with the anonymous type. See Example 5 below. </li>
1.87 + * </ul>
1.88 + * <b> Mapping to XML Schema Complex Type </b>
1.89 + * <ul>
1.90 + * <li>If class is annotated with <tt>@XmlType(name="") </tt>, it
1.91 + * is mapped to an anonymous type otherwise, the class name maps
1.92 + * to a complex type name. The <tt>XmlName()</tt> annotation element
1.93 + * can be used to customize the name.</li>
1.94 + *
1.95 + * <li> Properties and fields that are mapped to elements are mapped to a
1.96 + * content model within a complex type. The annotation element
1.97 + * <tt>propOrder()</tt> can be used to customize the content model to be
1.98 + * <tt>xs:all</tt> or <tt>xs:sequence</tt>. It is used for specifying
1.99 + * the order of XML elements in <tt>xs:sequence</tt>. </li>
1.100 + *
1.101 + * <li> Properties and fields can be mapped to attributes within the
1.102 + * complex type. </li>
1.103 + *
1.104 + * <li> The targetnamespace of the XML Schema type can be customized
1.105 + * using the annotation element <tt>namespace()</tt>. </li>
1.106 + * </ul>
1.107 + *
1.108 + * <p>
1.109 + * <b> Mapping class to XML Schema simple type </b>
1.110 + * <p>
1.111 + * A class can be mapped to a XML Schema simple type using the
1.112 + * <tt>@XmlValue</tt> annotation. For additional details and examples,
1.113 + * see @{@link XmlValue} annotation type.
1.114 + * <p>
1.115 + * The following table shows the mapping of the class to a XML Schema
1.116 + * complex type or simple type. The notational symbols used in the table are:
1.117 + * <ul>
1.118 + * <li> -> : represents a mapping </li>
1.119 + * <li> [x]+ : one or more occurances of x </li>
1.120 + * <li> [ <tt>@XmlValue</tt> property ]: JavaBean property annotated with
1.121 + * <tt>@XmlValue</tt></li>
1.122 + * <li> X : don't care
1.123 + * </ul>
1.124 + * <blockquote>
1.125 + * <table border="1" cellpadding="4" cellspacing="3">
1.126 + * <tbody>
1.127 + * <tr>
1.128 + * <td><b>Target</b></td>
1.129 + * <td><b>propOrder</b></td>
1.130 + * <td><b>ClassBody</b></td>
1.131 + * <td><b>ComplexType</b></td>
1.132 + * <td><b>SimpleType</b></td>
1.133 + * </tr>
1.134 + *
1.135 + * <tr valign="top">
1.136 + * <td>Class</td>
1.137 + * <td>{}</td>
1.138 + * <td>[property]+ -> elements</td>
1.139 + * <td>complexcontent<br>xs:all</td>
1.140 + * <td> </td>
1.141 + * </tr>
1.142 + *
1.143 + * <tr valign="top">
1.144 + * <td>Class</td>
1.145 + * <td>non empty</td>
1.146 + * <td>[property]+ -> elements</td>
1.147 + * <td>complexcontent<br>xs:sequence</td>
1.148 + * <td> </td>
1.149 + * </tr>
1.150 + *
1.151 + * <tr valign="top">
1.152 + * <td>Class</td>
1.153 + * <td>X</td>
1.154 + * <td>no property -> element</td>
1.155 + * <td>complexcontent<br>empty sequence</td>
1.156 + * <td> </td>
1.157 + * </tr>
1.158 + *
1.159 + * <tr valign="top">
1.160 + * <td>Class</td>
1.161 + * <td>X</td>
1.162 + * <td>1 [ <tt>@XmlValue</tt> property] && <br> [property]+
1.163 + * ->attributes</td>
1.164 + * <td>simplecontent</td>
1.165 + * <td> </td>
1.166 + * </tr>
1.167 + *
1.168 + * <tr valign="top">
1.169 + * <td>Class</td>
1.170 + * <td>X</td>
1.171 + * <td>1 [ <tt>@XmlValue</tt> property ]&& <br> no properties
1.172 + * -> attribute</td>
1.173 + * <td> </td>
1.174 + * <td>simpletype</td>
1.175 + * <td> </td>
1.176 + * </tr>
1.177 + * </tbody>
1.178 + * </table>
1.179 + * </blockquote>
1.180 + *
1.181 + * <h3> Mapping an enum type </h3>
1.182 + *
1.183 + * An enum type maps to a XML schema simple type with enumeration
1.184 + * facets. The following annotation elements are ignored since they
1.185 + * are not meaningful: <tt>propOrder()</tt> , <tt>factoryMethod()</tt> ,
1.186 + * <tt>factoryClass()</tt> .
1.187 + *
1.188 + * <h3> Usage with other annotations </h3>
1.189 + * <p> This annotation can be used with the following annotations:
1.190 + * {@link XmlRootElement}, {@link XmlAccessorOrder}, {@link XmlAccessorType},
1.191 + * {@link XmlEnum}. However, {@link
1.192 + * XmlAccessorOrder} and {@link XmlAccessorType} are ignored when this
1.193 + * annotation is used on an enum type.
1.194 + *
1.195 + * <p> <b> Example 1: </b> Map a class to a complex type with
1.196 + * xs:sequence with a customized ordering of JavaBean properties.
1.197 + * </p>
1.198 + *
1.199 + * <pre>
1.200 + * @XmlType(propOrder={"street", "city" , "state", "zip", "name" })
1.201 + * public class USAddress {
1.202 + * String getName() {..};
1.203 + * void setName(String) {..};
1.204 + *
1.205 + * String getStreet() {..};
1.206 + * void setStreet(String) {..};
1.207 + *
1.208 + * String getCity() {..};
1.209 + * void setCity(String) {..};
1.210 + *
1.211 + * String getState() {..};
1.212 + * void setState(String) {..};
1.213 + *
1.214 + * java.math.BigDecimal getZip() {..};
1.215 + * void setZip(java.math.BigDecimal) {..};
1.216 + * }
1.217 + *
1.218 + * <!-- XML Schema mapping for USAddress -->
1.219 + * <xs:complexType name="USAddress">
1.220 + * <xs:sequence>
1.221 + * <xs:element name="street" type="xs:string"/>
1.222 + * <xs:element name="city" type="xs:string"/>
1.223 + * <xs:element name="state" type="xs:string"/>
1.224 + * <xs:element name="zip" type="xs:decimal"/>
1.225 + * <xs:element name="name" type="xs:string"/>
1.226 + * </xs:all>
1.227 + * </xs:complexType>
1.228 + * </pre>
1.229 + * <p> <b> Example 2: </b> Map a class to a complex type with
1.230 + * xs:all </p>
1.231 + * <pre>
1.232 + * @XmlType(propOrder={})
1.233 + * public class USAddress { ...}
1.234 + *
1.235 + * <!-- XML Schema mapping for USAddress -->
1.236 + * <xs:complexType name="USAddress">
1.237 + * <xs:all>
1.238 + * <xs:element name="name" type="xs:string"/>
1.239 + * <xs:element name="street" type="xs:string"/>
1.240 + * <xs:element name="city" type="xs:string"/>
1.241 + * <xs:element name="state" type="xs:string"/>
1.242 + * <xs:element name="zip" type="xs:decimal"/>
1.243 + * </xs:sequence>
1.244 + * </xs:complexType>
1.245 + *</pre>
1.246 + * <p> <b> Example 3: </b> Map a class to a global element with an
1.247 + * anonymous type.
1.248 + * </p>
1.249 + * <pre>
1.250 + * @XmlRootElement
1.251 + * @XmlType(name="")
1.252 + * public class USAddress { ...}
1.253 + *
1.254 + * <!-- XML Schema mapping for USAddress -->
1.255 + * <xs:element name="USAddress">
1.256 + * <xs:complexType>
1.257 + * <xs:sequence>
1.258 + * <xs:element name="name" type="xs:string"/>
1.259 + * <xs:element name="street" type="xs:string"/>
1.260 + * <xs:element name="city" type="xs:string"/>
1.261 + * <xs:element name="state" type="xs:string"/>
1.262 + * <xs:element name="zip" type="xs:decimal"/>
1.263 + * </xs:sequence>
1.264 + * </xs:complexType>
1.265 + * </xs:element>
1.266 + * </pre>
1.267 + *
1.268 + * <p> <b> Example 4: </b> Map a property to a local element with
1.269 + * anonmyous type.
1.270 + * <pre>
1.271 + * //Example: Code fragment
1.272 + * public class Invoice {
1.273 + * USAddress addr;
1.274 + * ...
1.275 + * }
1.276 + *
1.277 + * @XmlType(name="")
1.278 + * public class USAddress { ... }
1.279 + * }
1.280 + *
1.281 + * <!-- XML Schema mapping for USAddress -->
1.282 + * <xs:complexType name="Invoice">
1.283 + * <xs:sequence>
1.284 + * <xs:element name="addr">
1.285 + * <xs:complexType>
1.286 + * <xs:element name="name", type="xs:string"/>
1.287 + * <xs:element name="city", type="xs:string"/>
1.288 + * <xs:element name="city" type="xs:string"/>
1.289 + * <xs:element name="state" type="xs:string"/>
1.290 + * <xs:element name="zip" type="xs:decimal"/>
1.291 + * </xs:complexType>
1.292 + * ...
1.293 + * </xs:sequence>
1.294 + * </xs:complexType>
1.295 + * </pre>
1.296 + *
1.297 + * <p> <b> Example 5: </b> Map a property to an attribute with
1.298 + * anonymous type.
1.299 + *
1.300 + * <pre>
1.301 + *
1.302 + * //Example: Code fragment
1.303 + * public class Item {
1.304 + * public String name;
1.305 + * @XmlAttribute
1.306 + * public USPrice price;
1.307 + * }
1.308 + *
1.309 + * // map class to anonymous simple type.
1.310 + * @XmlType(name="")
1.311 + * public class USPrice {
1.312 + * @XmlValue
1.313 + * public java.math.BigDecimal price;
1.314 + * }
1.315 + *
1.316 + * <!-- Example: XML Schema fragment -->
1.317 + * <xs:complexType name="Item">
1.318 + * <xs:sequence>
1.319 + * <xs:element name="name" type="xs:string"/>
1.320 + * <xs:attribute name="price">
1.321 + * <xs:simpleType>
1.322 + * <xs:restriction base="xs:decimal"/>
1.323 + * </xs:simpleType>
1.324 + * </xs:attribute>
1.325 + * </xs:sequence>
1.326 + * </xs:complexType>
1.327 + * </pre>
1.328 + *
1.329 + * <p> <b> Example 6: </b> Define a factoryClass and factoryMethod
1.330 + *
1.331 + * <pre>
1.332 + * @XmlType(name="USAddressType", factoryClass=USAddressFactory.class,
1.333 + * factoryMethod="getUSAddress")
1.334 + * public class USAddress {
1.335 + *
1.336 + * private String city;
1.337 + * private String name;
1.338 + * private String state;
1.339 + * private String street;
1.340 + * private int zip;
1.341 + *
1.342 + * public USAddress(String name, String street, String city,
1.343 + * String state, int zip) {
1.344 + * this.name = name;
1.345 + * this.street = street;
1.346 + * this.city = city;
1.347 + * this.state = state;
1.348 + * this.zip = zip;
1.349 + * }
1.350 + * }
1.351 + *
1.352 + * public class USAddressFactory {
1.353 + * public static USAddress getUSAddress(){
1.354 + * return new USAddress("Mark Baker", "23 Elm St",
1.355 + * "Dayton", "OH", 90952);
1.356 + * }
1.357 + *
1.358 + * </pre>
1.359 + *
1.360 + * <p> <b> Example 7: </b> Define factoryMethod and use the default factoryClass
1.361 + *
1.362 + * <pre>
1.363 + * @XmlType(name="USAddressType", factoryMethod="getNewInstance")
1.364 + * public class USAddress {
1.365 + *
1.366 + * private String city;
1.367 + * private String name;
1.368 + * private String state;
1.369 + * private String street;
1.370 + * private int zip;
1.371 + *
1.372 + * private USAddress() {}
1.373 + *
1.374 + * public static USAddress getNewInstance(){
1.375 + * return new USAddress();
1.376 + * }
1.377 + * }
1.378 + * </pre>
1.379 + *
1.380 + * @author Sekhar Vajjhala, Sun Microsystems, Inc.
1.381 + * @see XmlElement
1.382 + * @see XmlAttribute
1.383 + * @see XmlValue
1.384 + * @see XmlSchema
1.385 + * @since JAXB2.0
1.386 + */
1.387 +
1.388 +@Retention(RUNTIME) @Target({TYPE})
1.389 +public @interface XmlType {
1.390 + /**
1.391 + * Name of the XML Schema type which the class is mapped.
1.392 + */
1.393 + String name() default "##default" ;
1.394 +
1.395 + /**
1.396 + * Specifies the order for XML Schema elements when class is
1.397 + * mapped to a XML Schema complex type.
1.398 + *
1.399 + * <p> Refer to the table for how the propOrder affects the
1.400 + * mapping of class </p>
1.401 + *
1.402 + * <p> The propOrder is a list of names of JavaBean properties in
1.403 + * the class. Each name in the list is the name of a Java
1.404 + * identifier of the JavaBean property. The order in which
1.405 + * JavaBean properties are listed is the order of XML Schema
1.406 + * elements to which the JavaBean properties are mapped. </p>
1.407 + * <p> All of the JavaBean properties being mapped to XML Schema elements
1.408 + * must be listed.
1.409 + * <p> A JavaBean property or field listed in propOrder must not
1.410 + * be transient or annotated with <tt>@XmlTransient</tt>.
1.411 + * <p> The default ordering of JavaBean properties is determined
1.412 + * by @{@link XmlAccessorOrder}.
1.413 + */
1.414 + String[] propOrder() default {""};
1.415 +
1.416 + /**
1.417 + * Name of the target namespace of the XML Schema type. By
1.418 + * default, this is the target namespace to which the package
1.419 + * containing the class is mapped.
1.420 + */
1.421 + String namespace() default "##default" ;
1.422 +
1.423 + /**
1.424 + * Class containing a no-arg factory method for creating an
1.425 + * instance of this class. The default is this class.
1.426 + *
1.427 + * <p>If <tt>factoryClass</tt> is DEFAULT.class and
1.428 + * <tt>factoryMethod</tt> is "", then there is no static factory
1.429 + * method.
1.430 + *
1.431 + * <p>If <tt>factoryClass</tt> is DEFAULT.class and
1.432 + * <tt>factoryMethod</tt> is not "", then
1.433 + * <tt>factoryMethod</tt> is the name of a static factory method
1.434 + * in this class.
1.435 + *
1.436 + * <p>If <tt>factoryClass</tt> is not DEFAULT.class, then
1.437 + * <tt>factoryMethod</tt> must not be "" and must be the name of
1.438 + * a static factory method specified in <tt>factoryClass</tt>.
1.439 + */
1.440 + Class factoryClass() default DEFAULT.class;
1.441 +
1.442 + /**
1.443 + * Used in {@link XmlType#factoryClass()} to
1.444 + * signal that either factory mehod is not used or
1.445 + * that it's in the class with this {@link XmlType} itself.
1.446 + */
1.447 + static final class DEFAULT {}
1.448 +
1.449 + /**
1.450 + * Name of a no-arg factory method in the class specified in
1.451 + * <tt>factoryClass</tt> factoryClass().
1.452 + *
1.453 + */
1.454 + String factoryMethod() default "";
1.455 +}
