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> {@literal ->} : 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]+ {@literal ->} 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]+ {@literal ->} 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 {@literal ->} 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]+ {@literal ->} 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 {@literal ->} 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) {..}; 389 /** 390 * Name of the XML Schema type which the class is mapped. 391 */ 392 String name() default "##default" ; 393 394 /** 395 * Specifies the order for XML Schema elements when class is 396 * mapped to a XML Schema complex type. 397 * 398 * <p> Refer to the table for how the propOrder affects the 399 * mapping of class </p> 400 * 401 * <p> The propOrder is a list of names of JavaBean properties in 402 * the class. Each name in the list is the name of a Java 403 * identifier of the JavaBean property. The order in which 404 * JavaBean properties are listed is the order of XML Schema 405 * elements to which the JavaBean properties are mapped. </p> 406 * <p> All of the JavaBean properties being mapped to XML Schema elements 407 * must be listed. 408 * <p> A JavaBean property or field listed in propOrder must not 409 * be transient or annotated with <tt>@XmlTransient</tt>. 410 * <p> The default ordering of JavaBean properties is determined 411 * by @{@link XmlAccessorOrder}. 412 */ 413 String[] propOrder() default {""}; 414 415 /** 416 * Name of the target namespace of the XML Schema type. By 417 * default, this is the target namespace to which the package 418 * containing the class is mapped. 419 */ 420 String namespace() default "##default" ; 421 422 /** 423 * Class containing a no-arg factory method for creating an 424 * instance of this class. The default is this class. 425 * 426 * <p>If <tt>factoryClass</tt> is DEFAULT.class and 427 * <tt>factoryMethod</tt> is "", then there is no static factory 428 * method. 429 * 430 * <p>If <tt>factoryClass</tt> is DEFAULT.class and 431 * <tt>factoryMethod</tt> is not "", then 432 * <tt>factoryMethod</tt> is the name of a static factory method 433 * in this class. 434 * 435 * <p>If <tt>factoryClass</tt> is not DEFAULT.class, then 436 * <tt>factoryMethod</tt> must not be "" and must be the name of 437 * a static factory method specified in <tt>factoryClass</tt>. 438 */ 439 Class factoryClass() default DEFAULT.class; 440 441 /** 442 * Used in {@link XmlType#factoryClass()} to 443 * signal that either factory mehod is not used or 444 * that it's in the class with this {@link XmlType} itself. 445 */ 446 static final class DEFAULT {} 447 448 /** 449 * Name of a no-arg factory method in the class specified in 450 * <tt>factoryClass</tt> factoryClass(). 451 * 452 */ 453 String factoryMethod() default ""; 454 } | 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 {@code @XmlType} 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 {@code factoryMethod()} and 57 * {@code factoryClass()} 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 {@code @XmlType(name="")}. 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 {@code @XmlType(name="") }, it 88 * is mapped to an anonymous type otherwise, the class name maps 89 * to a complex type name. The {@code XmlName()} 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 * {@code propOrder()} can be used to customize the content model to be 95 * {@code xs:all} or {@code xs:sequence}. It is used for specifying 96 * the order of XML elements in {@code xs:sequence}. </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 {@code namespace()}. </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 * {@code @XmlValue} 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> {@literal ->} : represents a mapping </li> 116 * <li> [x]+ : one or more occurances of x </li> 117 * <li> [ {@code @XmlValue} property ]: JavaBean property annotated with 118 * {@code @XmlValue}</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]+ {@literal ->} 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]+ {@literal ->} 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 {@literal ->} 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 [{@code @XmlValue} property] {@literal &&} <br> [property]+ {@literal ->} 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 [{@code @XmlValue} property] {@literal &&} <br> no properties {@literal ->} 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: {@code propOrder()} , {@code factoryMethod()} , 180 * {@code factoryClass()} . 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) {..}; 389 /** 390 * Name of the XML Schema type which the class is mapped. 391 */ 392 String name() default "##default" ; 393 394 /** 395 * Specifies the order for XML Schema elements when class is 396 * mapped to a XML Schema complex type. 397 * 398 * <p> Refer to the table for how the propOrder affects the 399 * mapping of class </p> 400 * 401 * <p> The propOrder is a list of names of JavaBean properties in 402 * the class. Each name in the list is the name of a Java 403 * identifier of the JavaBean property. The order in which 404 * JavaBean properties are listed is the order of XML Schema 405 * elements to which the JavaBean properties are mapped. </p> 406 * <p> All of the JavaBean properties being mapped to XML Schema elements 407 * must be listed. 408 * <p> A JavaBean property or field listed in propOrder must not 409 * be transient or annotated with {@code @XmlTransient}. 410 * <p> The default ordering of JavaBean properties is determined 411 * by @{@link XmlAccessorOrder}. 412 */ 413 String[] propOrder() default {""}; 414 415 /** 416 * Name of the target namespace of the XML Schema type. By 417 * default, this is the target namespace to which the package 418 * containing the class is mapped. 419 */ 420 String namespace() default "##default" ; 421 422 /** 423 * Class containing a no-arg factory method for creating an 424 * instance of this class. The default is this class. 425 * 426 * <p>If {@code factoryClass} is DEFAULT.class and 427 * {@code factoryMethod} is "", then there is no static factory 428 * method. 429 * 430 * <p>If {@code factoryClass} is DEFAULT.class and 431 * {@code factoryMethod} is not "", then 432 * {@code factoryMethod} is the name of a static factory method 433 * in this class. 434 * 435 * <p>If {@code factoryClass} is not DEFAULT.class, then 436 * {@code factoryMethod} must not be "" and must be the name of 437 * a static factory method specified in {@code factoryClass}. 438 */ 439 Class factoryClass() default DEFAULT.class; 440 441 /** 442 * Used in {@link XmlType#factoryClass()} to 443 * signal that either factory mehod is not used or 444 * that it's in the class with this {@link XmlType} itself. 445 */ 446 static final class DEFAULT {} 447 448 /** 449 * Name of a no-arg factory method in the class specified in 450 * {@code factoryClass} factoryClass(). 451 * 452 */ 453 String factoryMethod() default ""; 454 } |