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 static java.lang.annotation.ElementType.TYPE; 29 import java.lang.annotation.Retention; 30 import static java.lang.annotation.RetentionPolicy.RUNTIME; 31 import java.lang.annotation.Target; 32 33 /** 34 * <p> 35 * Maps a class or an enum type to a XML Schema type. 36 * 37 * <p><b>Usage</b></p> 38 * <p> The <tt>@XmlType</tt> annnotation can be used with the following program 39 * elements: 40 * <ul> 41 * <li> a top level class </li> 42 * <li> an enum type </li> 43 * </ul> 44 * 45 * <p>See "Package Specification" in javax.xml.bind.package javadoc for 46 * additional common information.</p> 47 * 48 * <h3> Mapping a Class </h3> 49 * <p> 50 * A class maps to a XML Schema type. A class is a data container for 51 * values represented by properties and fields. A schema type is a 52 * data container for values represented by schema components within a 53 * schema type's content model (e.g. model groups, attributes etc). 54 * <p> To be mapped, a class must either have a public no-arg 55 * constructor or a static no-arg factory method. The static factory 56 * method can be specified in <tt>factoryMethod()</tt> and 57 * <tt>factoryClass()</tt> annotation elements. The static factory 58 * method or the no-arg constructor is used during unmarshalling to 59 * create an instance of this class. If both are present, the static 60 * factory method overrides the no-arg constructor. 61 * <p> 62 * A class maps to either a XML Schema complex type or a XML Schema simple 63 * type. The XML Schema type is derived based on the 64 * mapping of JavaBean properties and fields contained within the 65 * class. The schema type to which the class is mapped can either be 66 * named or anonymous. A class can be mapped to an anonymous schema 67 * type by annotating the class with <tt>@XmlType(name="")</tt>. 68 * <p> 69 * Either a global element, local element or a local attribute can be 70 * associated with an anonymous type as follows: 71 * <ul> 72 * <li><b>global element: </b> A global element of an anonymous 73 * type can be derived by annotating the class with @{@link 74 * XmlRootElement}. See Example 3 below. </li> 75 * 76 * <li><b>local element: </b> A JavaBean property that references 77 * a class annotated with @XmlType(name="") and is mapped to the 78 * element associated with the anonymous type. See Example 4 79 * below.</li> 80 * 81 * <li><b>attribute: </b> A JavaBean property that references 82 * a class annotated with @XmlType(name="") and is mapped to the 83 * attribute associated with the anonymous type. See Example 5 below. </li> 84 * </ul> 85 * <b> Mapping to XML Schema Complex Type </b> 86 * <ul> 87 * <li>If class is annotated with <tt>@XmlType(name="") </tt>, it 88 * is mapped to an anonymous type otherwise, the class name maps 89 * to a complex type name. The <tt>XmlName()</tt> annotation element 90 * can be used to customize the name.</li> 91 * 92 * <li> Properties and fields that are mapped to elements are mapped to a 93 * content model within a complex type. The annotation element 94 * <tt>propOrder()</tt> can be used to customize the content model to be 95 * <tt>xs:all</tt> or <tt>xs:sequence</tt>. It is used for specifying 96 * the order of XML elements in <tt>xs:sequence</tt>. </li> 97 * 98 * <li> Properties and fields can be mapped to attributes within the 99 * complex type. </li> 100 * 101 * <li> The targetnamespace of the XML Schema type can be customized 102 * using the annotation element <tt>namespace()</tt>. </li> 103 * </ul> 104 * 105 * <p> 106 * <b> Mapping class to XML Schema simple type </b> 107 * <p> 108 * A class can be mapped to a XML Schema simple type using the 109 * <tt>@XmlValue</tt> annotation. For additional details and examples, 110 * see @{@link XmlValue} annotation type. 111 * <p> 112 * The following table shows the mapping of the class to a XML Schema 113 * complex type or simple type. The notational symbols used in the table are: 114 * <ul> 115 * <li> -> : represents a mapping </li> 116 * <li> [x]+ : one or more occurances of x </li> 117 * <li> [ <tt>@XmlValue</tt> property ]: JavaBean property annotated with 118 * <tt>@XmlValue</tt></li> 119 * <li> X : don't care 120 * </ul> 121 * <blockquote> 122 * <table summary="" border="1" cellpadding="4" cellspacing="3"> 123 * <tbody> 124 * <tr> 125 * <td><b>Target</b></td> 126 * <td><b>propOrder</b></td> 127 * <td><b>ClassBody</b></td> 128 * <td><b>ComplexType</b></td> 129 * <td><b>SimpleType</b></td> 130 * </tr> 131 * 132 * <tr valign="top"> 133 * <td>Class</td> 134 * <td>{}</td> 135 * <td>[property]+ -> elements</td> 136 * <td>complexcontent<br>xs:all</td> 137 * <td> </td> 138 * </tr> 139 * 140 * <tr valign="top"> 141 * <td>Class</td> 142 * <td>non empty</td> 143 * <td>[property]+ -> elements</td> 144 * <td>complexcontent<br>xs:sequence</td> 145 * <td> </td> 146 * </tr> 147 * 148 * <tr valign="top"> 149 * <td>Class</td> 150 * <td>X</td> 151 * <td>no property -> element</td> 152 * <td>complexcontent<br>empty sequence</td> 153 * <td> </td> 154 * </tr> 155 * 156 * <tr valign="top"> 157 * <td>Class</td> 158 * <td>X</td> 159 * <td>1 [<tt>@XmlValue</tt> property] {@literal &&} <br> [property]+ -> attributes</td> 160 * <td>simplecontent</td> 161 * <td> </td> 162 * </tr> 163 * 164 * <tr valign="top"> 165 * <td>Class</td> 166 * <td>X</td> 167 * <td>1 [<tt>@XmlValue</tt> property] {@literal &&} <br> no properties -> attribute</td> 168 * <td> </td> 169 * <td>simpletype</td> 170 * </tr> 171 * </tbody> 172 * </table> 173 * </blockquote> 174 * 175 * <h3> Mapping an enum type </h3> 176 * 177 * An enum type maps to a XML schema simple type with enumeration 178 * facets. The following annotation elements are ignored since they 179 * are not meaningful: <tt>propOrder()</tt> , <tt>factoryMethod()</tt> , 180 * <tt>factoryClass()</tt> . 181 * 182 * <h3> Usage with other annotations </h3> 183 * <p> This annotation can be used with the following annotations: 184 * {@link XmlRootElement}, {@link XmlAccessorOrder}, {@link XmlAccessorType}, 185 * {@link XmlEnum}. However, {@link 186 * XmlAccessorOrder} and {@link XmlAccessorType} are ignored when this 187 * annotation is used on an enum type. 188 * 189 * <p> <b> Example 1: </b> Map a class to a complex type with 190 * xs:sequence with a customized ordering of JavaBean properties. 191 * </p> 192 * 193 * <pre> 194 * @XmlType(propOrder={"street", "city" , "state", "zip", "name" }) 195 * public class USAddress { 196 * String getName() {..}; 197 * void setName(String) {..}; 198 * 199 * String getStreet() {..}; 200 * void setStreet(String) {..}; 201 * 202 * String getCity() {..}; 203 * void setCity(String) {..}; 204 * 205 * String getState() {..}; 206 * void setState(String) {..}; 207 * 208 * java.math.BigDecimal getZip() {..}; 209 * void setZip(java.math.BigDecimal) {..}; 210 * } 211 * 212 * <!-- XML Schema mapping for USAddress --> 213 * <xs:complexType name="USAddress"> 214 * <xs:sequence> 215 * <xs:element name="street" type="xs:string"/> 216 * <xs:element name="city" type="xs:string"/> 217 * <xs:element name="state" type="xs:string"/> 218 * <xs:element name="zip" type="xs:decimal"/> 219 * <xs:element name="name" type="xs:string"/> 220 * </xs:all> 221 * </xs:complexType> 222 * </pre> 223 * <p> <b> Example 2: </b> Map a class to a complex type with 224 * xs:all </p> 225 * <pre> 226 * @XmlType(propOrder={}) 227 * public class USAddress { ...} 228 * 229 * <!-- XML Schema mapping for USAddress --> 230 * <xs:complexType name="USAddress"> 231 * <xs:all> 232 * <xs:element name="name" type="xs:string"/> 233 * <xs:element name="street" type="xs:string"/> 234 * <xs:element name="city" type="xs:string"/> 235 * <xs:element name="state" type="xs:string"/> 236 * <xs:element name="zip" type="xs:decimal"/> 237 * </xs:sequence> 238 * </xs:complexType> 239 *</pre> 240 * <p> <b> Example 3: </b> Map a class to a global element with an 241 * anonymous type. 242 * </p> 243 * <pre> 244 * @XmlRootElement 245 * @XmlType(name="") 246 * public class USAddress { ...} 247 * 248 * <!-- XML Schema mapping for USAddress --> 249 * <xs:element name="USAddress"> 250 * <xs:complexType> 251 * <xs:sequence> 252 * <xs:element name="name" type="xs:string"/> 253 * <xs:element name="street" type="xs:string"/> 254 * <xs:element name="city" type="xs:string"/> 255 * <xs:element name="state" type="xs:string"/> 256 * <xs:element name="zip" type="xs:decimal"/> 257 * </xs:sequence> 258 * </xs:complexType> 259 * </xs:element> 260 * </pre> 261 * 262 * <p> <b> Example 4: </b> Map a property to a local element with 263 * anonymous type. 264 * <pre> 265 * //Example: Code fragment 266 * public class Invoice { 267 * USAddress addr; 268 * ... 269 * } 270 * 271 * @XmlType(name="") 272 * public class USAddress { ... } 273 * } 274 * 275 * <!-- XML Schema mapping for USAddress --> 276 * <xs:complexType name="Invoice"> 277 * <xs:sequence> 278 * <xs:element name="addr"> 279 * <xs:complexType> 280 * <xs:element name="name", type="xs:string"/> 281 * <xs:element name="city", type="xs:string"/> 282 * <xs:element name="city" type="xs:string"/> 283 * <xs:element name="state" type="xs:string"/> 284 * <xs:element name="zip" type="xs:decimal"/> 285 * </xs:complexType> 286 * ... 287 * </xs:sequence> 288 * </xs:complexType> 289 * </pre> 290 * 291 * <p> <b> Example 5: </b> Map a property to an attribute with 292 * anonymous type. 293 * 294 * <pre> 295 * 296 * //Example: Code fragment 297 * public class Item { 298 * public String name; 299 * @XmlAttribute 300 * public USPrice price; 301 * } 302 * 303 * // map class to anonymous simple type. 304 * @XmlType(name="") 305 * public class USPrice { 306 * @XmlValue 307 * public java.math.BigDecimal price; 308 * } 309 * 310 * <!-- Example: XML Schema fragment --> 311 * <xs:complexType name="Item"> 312 * <xs:sequence> 313 * <xs:element name="name" type="xs:string"/> 314 * <xs:attribute name="price"> 315 * <xs:simpleType> 316 * <xs:restriction base="xs:decimal"/> 317 * </xs:simpleType> 318 * </xs:attribute> 319 * </xs:sequence> 320 * </xs:complexType> 321 * </pre> 322 * 323 * <p> <b> Example 6: </b> Define a factoryClass and factoryMethod 324 * 325 * <pre> 326 * @XmlType(name="USAddressType", factoryClass=USAddressFactory.class, 327 * factoryMethod="getUSAddress") 328 * public class USAddress { 329 * 330 * private String city; 331 * private String name; 332 * private String state; 333 * private String street; 334 * private int zip; 335 * 336 * public USAddress(String name, String street, String city, 337 * String state, int zip) { 338 * this.name = name; 339 * this.street = street; 340 * this.city = city; 341 * this.state = state; 342 * this.zip = zip; 343 * } 344 * } 345 * 346 * public class USAddressFactory { 347 * public static USAddress getUSAddress(){ 348 * return new USAddress("Mark Baker", "23 Elm St", 349 * "Dayton", "OH", 90952); 350 * } 351 * 352 * </pre> 353 * 354 * <p> <b> Example 7: </b> Define factoryMethod and use the default factoryClass 355 * 356 * <pre> 357 * @XmlType(name="USAddressType", factoryMethod="getNewInstance") 358 * public class USAddress { 359 * 360 * private String city; 361 * private String name; 362 * private String state; 363 * private String street; 364 * private int zip; 365 * 366 * private USAddress() {} 367 * 368 * public static USAddress getNewInstance(){ 369 * return new USAddress(); 370 * } 371 * } 372 * </pre> 373 * 374 * @author Sekhar Vajjhala, Sun Microsystems, Inc. 375 * @see XmlElement 376 * @see XmlAttribute 377 * @see XmlValue 378 * @see XmlSchema 379 * @since 1.6, JAXB 2.0 380 */ 381 382 @Retention(RUNTIME) @Target({TYPE}) 383 public @interface XmlType { 384 /** 385 * Name of the XML Schema type which the class is mapped. 386 */ 387 String name() default "##default" ; 388 389 /** 390 * Specifies the order for XML Schema elements when class is 391 * mapped to a XML Schema complex type. 392 * 393 * <p> Refer to the table for how the propOrder affects the 394 * mapping of class </p> 395 * 396 * <p> The propOrder is a list of names of JavaBean properties in 397 * the class. Each name in the list is the name of a Java 398 * identifier of the JavaBean property. The order in which 399 * JavaBean properties are listed is the order of XML Schema 400 * elements to which the JavaBean properties are mapped. </p> 401 * <p> All of the JavaBean properties being mapped to XML Schema elements 402 * must be listed. 403 * <p> A JavaBean property or field listed in propOrder must not 404 * be transient or annotated with <tt>@XmlTransient</tt>. 405 * <p> The default ordering of JavaBean properties is determined 406 * by @{@link XmlAccessorOrder}. 407 */ 408 String[] propOrder() default {""}; 409 410 /** 411 * Name of the target namespace of the XML Schema type. By 412 * default, this is the target namespace to which the package 413 * containing the class is mapped. 414 */ 415 String namespace() default "##default" ; 416 417 /** 418 * Class containing a no-arg factory method for creating an 419 * instance of this class. The default is this class. 420 * 421 * <p>If <tt>factoryClass</tt> is DEFAULT.class and 422 * <tt>factoryMethod</tt> is "", then there is no static factory 423 * method. 424 * 425 * <p>If <tt>factoryClass</tt> is DEFAULT.class and 426 * <tt>factoryMethod</tt> is not "", then 427 * <tt>factoryMethod</tt> is the name of a static factory method 428 * in this class. 429 * 430 * <p>If <tt>factoryClass</tt> is not DEFAULT.class, then 431 * <tt>factoryMethod</tt> must not be "" and must be the name of 432 * a static factory method specified in <tt>factoryClass</tt>. 433 */ 434 Class factoryClass() default DEFAULT.class; 435 436 /** 437 * Used in {@link XmlType#factoryClass()} to 438 * signal that either factory mehod is not used or 439 * that it's in the class with this {@link XmlType} itself. 440 */ 441 static final class DEFAULT {} 442 443 /** 444 * Name of a no-arg factory method in the class specified in 445 * <tt>factoryClass</tt> factoryClass(). 446 * 447 */ 448 String factoryMethod() default ""; 449 }