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 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 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] && <br> [property]+ 160 * ->attributes</td> 161 * <td>simplecontent</td> 162 * <td> </td> 163 * </tr> 164 * 165 * <tr valign="top"> 166 * <td>Class</td> 167 * <td>X</td> 168 * <td>1 [ <tt>@XmlValue</tt> property ]&& <br> no properties 169 * -> attribute</td> 170 * <td> </td> 171 * <td>simpletype</td> 172 * <td> </td> 173 * </tr> 174 * </tbody> 175 * </table> 176 * </blockquote> 177 * 178 * <h3> Mapping an enum type </h3> 179 * 180 * An enum type maps to a XML schema simple type with enumeration 181 * facets. The following annotation elements are ignored since they 182 * are not meaningful: <tt>propOrder()</tt> , <tt>factoryMethod()</tt> , 183 * <tt>factoryClass()</tt> . 184 * 185 * <h3> Usage with other annotations </h3> 186 * <p> This annotation can be used with the following annotations: 187 * {@link XmlRootElement}, {@link XmlAccessorOrder}, {@link XmlAccessorType}, 188 * {@link XmlEnum}. However, {@link 189 * XmlAccessorOrder} and {@link XmlAccessorType} are ignored when this 190 * annotation is used on an enum type. 191 * 192 * <p> <b> Example 1: </b> Map a class to a complex type with 193 * xs:sequence with a customized ordering of JavaBean properties. 194 * </p> 195 * 196 * <pre> 197 * @XmlType(propOrder={"street", "city" , "state", "zip", "name" }) 198 * public class USAddress { 199 * String getName() {..}; 200 * void setName(String) {..}; 201 * 202 * String getStreet() {..}; 203 * void setStreet(String) {..}; 204 * 205 * String getCity() {..}; 206 * void setCity(String) {..}; 207 * 208 * String getState() {..}; 209 * void setState(String) {..}; 210 * 211 * java.math.BigDecimal getZip() {..}; 212 * void setZip(java.math.BigDecimal) {..}; 213 * } 214 * 215 * <!-- XML Schema mapping for USAddress --> 216 * <xs:complexType name="USAddress"> 217 * <xs:sequence> 218 * <xs:element name="street" type="xs:string"/> 219 * <xs:element name="city" type="xs:string"/> 220 * <xs:element name="state" type="xs:string"/> 221 * <xs:element name="zip" type="xs:decimal"/> 222 * <xs:element name="name" type="xs:string"/> 223 * </xs:all> 224 * </xs:complexType> 225 * </pre> 226 * <p> <b> Example 2: </b> Map a class to a complex type with 227 * xs:all </p> 228 * <pre> 229 * @XmlType(propOrder={}) 230 * public class USAddress { ...} 231 * 232 * <!-- XML Schema mapping for USAddress --> 233 * <xs:complexType name="USAddress"> 234 * <xs:all> 235 * <xs:element name="name" type="xs:string"/> 236 * <xs:element name="street" type="xs:string"/> 237 * <xs:element name="city" type="xs:string"/> 238 * <xs:element name="state" type="xs:string"/> 239 * <xs:element name="zip" type="xs:decimal"/> 240 * </xs:sequence> 241 * </xs:complexType> 242 *</pre> 243 * <p> <b> Example 3: </b> Map a class to a global element with an 244 * anonymous type. 245 * </p> 246 * <pre> 247 * @XmlRootElement 248 * @XmlType(name="") 249 * public class USAddress { ...} 250 * 251 * <!-- XML Schema mapping for USAddress --> 252 * <xs:element name="USAddress"> 253 * <xs:complexType> 254 * <xs:sequence> 255 * <xs:element name="name" type="xs:string"/> 256 * <xs:element name="street" type="xs:string"/> 257 * <xs:element name="city" type="xs:string"/> 258 * <xs:element name="state" type="xs:string"/> 259 * <xs:element name="zip" type="xs:decimal"/> 260 * </xs:sequence> 261 * </xs:complexType> 262 * </xs:element> 263 * </pre> 264 * 265 * <p> <b> Example 4: </b> Map a property to a local element with 266 * anonmyous type. 267 * <pre> 268 * //Example: Code fragment 269 * public class Invoice { 270 * USAddress addr; 271 * ... 272 * } 273 * 274 * @XmlType(name="") 275 * public class USAddress { ... } 276 * } 277 * 278 * <!-- XML Schema mapping for USAddress --> 279 * <xs:complexType name="Invoice"> 280 * <xs:sequence> 281 * <xs:element name="addr"> 282 * <xs:complexType> 283 * <xs:element name="name", type="xs:string"/> 284 * <xs:element name="city", type="xs:string"/> 285 * <xs:element name="city" type="xs:string"/> 286 * <xs:element name="state" type="xs:string"/> 287 * <xs:element name="zip" type="xs:decimal"/> 288 * </xs:complexType> 289 * ... 290 * </xs:sequence> 291 * </xs:complexType> 292 * </pre> 293 * 294 * <p> <b> Example 5: </b> Map a property to an attribute with 295 * anonymous type. 296 * 297 * <pre> 298 * 299 * //Example: Code fragment 300 * public class Item { 301 * public String name; 302 * @XmlAttribute 303 * public USPrice price; 304 * } 305 * 306 * // map class to anonymous simple type. 307 * @XmlType(name="") 308 * public class USPrice { 309 * @XmlValue 310 * public java.math.BigDecimal price; 311 * } 312 * 313 * <!-- Example: XML Schema fragment --> 314 * <xs:complexType name="Item"> 315 * <xs:sequence> 316 * <xs:element name="name" type="xs:string"/> 317 * <xs:attribute name="price"> 318 * <xs:simpleType> 319 * <xs:restriction base="xs:decimal"/> 320 * </xs:simpleType> 321 * </xs:attribute> 322 * </xs:sequence> 323 * </xs:complexType> 324 * </pre> 325 * 326 * <p> <b> Example 6: </b> Define a factoryClass and factoryMethod 327 * 328 * <pre> 329 * @XmlType(name="USAddressType", factoryClass=USAddressFactory.class, 330 * factoryMethod="getUSAddress") 331 * public class USAddress { 332 * 333 * private String city; 334 * private String name; 335 * private String state; 336 * private String street; 337 * private int zip; 338 * 339 * public USAddress(String name, String street, String city, 340 * String state, int zip) { 341 * this.name = name; 342 * this.street = street; 343 * this.city = city; 344 * this.state = state; 345 * this.zip = zip; 346 * } 347 * } 348 * 349 * public class USAddressFactory { 350 * public static USAddress getUSAddress(){ 351 * return new USAddress("Mark Baker", "23 Elm St", 352 * "Dayton", "OH", 90952); 353 * } 354 * 355 * </pre> 356 * 357 * <p> <b> Example 7: </b> Define factoryMethod and use the default factoryClass 358 * 359 * <pre> 360 * @XmlType(name="USAddressType", factoryMethod="getNewInstance") 361 * public class USAddress { 362 * 363 * private String city; 364 * private String name; 365 * private String state; 366 * private String street; 367 * private int zip; 368 * 369 * private USAddress() {} 370 * 371 * public static USAddress getNewInstance(){ 372 * return new USAddress(); 373 * } 374 * } 375 * </pre> 376 * 377 * @author Sekhar Vajjhala, Sun Microsystems, Inc. 378 * @see XmlElement 379 * @see XmlAttribute 380 * @see XmlValue 381 * @see XmlSchema 382 * @since 1.6, JAXB 2.0 383 */ 384 385 @Retention(RUNTIME) @Target({TYPE}) 386 public @interface XmlType { 387 /** 388 * Name of the XML Schema type which the class is mapped. 389 */ 390 String name() default "##default" ; 391 392 /** 393 * Specifies the order for XML Schema elements when class is 394 * mapped to a XML Schema complex type. 395 * 396 * <p> Refer to the table for how the propOrder affects the 397 * mapping of class </p> 398 * 399 * <p> The propOrder is a list of names of JavaBean properties in 400 * the class. Each name in the list is the name of a Java 401 * identifier of the JavaBean property. The order in which 402 * JavaBean properties are listed is the order of XML Schema 403 * elements to which the JavaBean properties are mapped. </p> 404 * <p> All of the JavaBean properties being mapped to XML Schema elements 405 * must be listed. 406 * <p> A JavaBean property or field listed in propOrder must not 407 * be transient or annotated with <tt>@XmlTransient</tt>. 408 * <p> The default ordering of JavaBean properties is determined 409 * by @{@link XmlAccessorOrder}. 410 */ 411 String[] propOrder() default {""}; 412 413 /** 414 * Name of the target namespace of the XML Schema type. By 415 * default, this is the target namespace to which the package 416 * containing the class is mapped. 417 */ 418 String namespace() default "##default" ; 419 420 /** 421 * Class containing a no-arg factory method for creating an 422 * instance of this class. The default is this class. 423 * 424 * <p>If <tt>factoryClass</tt> is DEFAULT.class and 425 * <tt>factoryMethod</tt> is "", then there is no static factory 426 * method. 427 * 428 * <p>If <tt>factoryClass</tt> is DEFAULT.class and 429 * <tt>factoryMethod</tt> is not "", then 430 * <tt>factoryMethod</tt> is the name of a static factory method 431 * in this class. 432 * 433 * <p>If <tt>factoryClass</tt> is not DEFAULT.class, then 434 * <tt>factoryMethod</tt> must not be "" and must be the name of 435 * a static factory method specified in <tt>factoryClass</tt>. 436 */ 437 Class factoryClass() default DEFAULT.class; 438 439 /** 440 * Used in {@link XmlType#factoryClass()} to 441 * signal that either factory mehod is not used or 442 * that it's in the class with this {@link XmlType} itself. 443 */ 444 static final class DEFAULT {} 445 446 /** 447 * Name of a no-arg factory method in the class specified in 448 * <tt>factoryClass</tt> factoryClass(). 449 * 450 */ 451 String factoryMethod() default ""; 452 }