51 * values represented by properties and fields. A schema type is a |
51 * values represented by properties and fields. A schema type is a |
52 * data container for values represented by schema components within a |
52 * data container for values represented by schema components within a |
53 * schema type's content model (e.g. model groups, attributes etc). |
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 |
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 |
55 * constructor or a static no-arg factory method. The static factory |
56 * method can be specified in <tt>factoryMethod()</tt> and |
56 * method can be specified in {@code factoryMethod()} and |
57 * <tt>factoryClass()</tt> annotation elements. The static factory |
57 * {@code factoryClass()} annotation elements. The static factory |
58 * method or the no-arg constructor is used during unmarshalling to |
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 |
59 * create an instance of this class. If both are present, the static |
60 * factory method overrides the no-arg constructor. |
60 * factory method overrides the no-arg constructor. |
61 * <p> |
61 * <p> |
62 * A class maps to either a XML Schema complex type or a XML Schema simple |
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 |
63 * type. The XML Schema type is derived based on the |
64 * mapping of JavaBean properties and fields contained within 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 |
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 |
66 * named or anonymous. A class can be mapped to an anonymous schema |
67 * type by annotating the class with <tt>@XmlType(name="")</tt>. |
67 * type by annotating the class with {@code @XmlType(name="")}. |
68 * <p> |
68 * <p> |
69 * Either a global element, local element or a local attribute can be |
69 * Either a global element, local element or a local attribute can be |
70 * associated with an anonymous type as follows: |
70 * associated with an anonymous type as follows: |
71 * <ul> |
71 * <ul> |
72 * <li><b>global element: </b> A global element of an anonymous |
72 * <li><b>global element: </b> A global element of an anonymous |
82 * a class annotated with @XmlType(name="") and is mapped to the |
82 * a class annotated with @XmlType(name="") and is mapped to the |
83 * attribute associated with the anonymous type. See Example 5 below. </li> |
83 * attribute associated with the anonymous type. See Example 5 below. </li> |
84 * </ul> |
84 * </ul> |
85 * <b> Mapping to XML Schema Complex Type </b> |
85 * <b> Mapping to XML Schema Complex Type </b> |
86 * <ul> |
86 * <ul> |
87 * <li>If class is annotated with <tt>@XmlType(name="") </tt>, it |
87 * <li>If class is annotated with {@code @XmlType(name="") }, it |
88 * is mapped to an anonymous type otherwise, the class name maps |
88 * is mapped to an anonymous type otherwise, the class name maps |
89 * to a complex type name. The <tt>XmlName()</tt> annotation element |
89 * to a complex type name. The {@code XmlName()} annotation element |
90 * can be used to customize the name.</li> |
90 * can be used to customize the name.</li> |
91 * |
91 * |
92 * <li> Properties and fields that are mapped to elements are mapped to a |
92 * <li> Properties and fields that are mapped to elements are mapped to a |
93 * content model within a complex type. The annotation element |
93 * content model within a complex type. The annotation element |
94 * <tt>propOrder()</tt> can be used to customize the content model to be |
94 * {@code propOrder()} 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 |
95 * {@code xs:all} or {@code xs:sequence}. It is used for specifying |
96 * the order of XML elements in <tt>xs:sequence</tt>. </li> |
96 * the order of XML elements in {@code xs:sequence}. </li> |
97 * |
97 * |
98 * <li> Properties and fields can be mapped to attributes within the |
98 * <li> Properties and fields can be mapped to attributes within the |
99 * complex type. </li> |
99 * complex type. </li> |
100 * |
100 * |
101 * <li> The targetnamespace of the XML Schema type can be customized |
101 * <li> The targetnamespace of the XML Schema type can be customized |
102 * using the annotation element <tt>namespace()</tt>. </li> |
102 * using the annotation element {@code namespace()}. </li> |
103 * </ul> |
103 * </ul> |
104 * |
104 * |
105 * <p> |
105 * <p> |
106 * <b> Mapping class to XML Schema simple type </b> |
106 * <b> Mapping class to XML Schema simple type </b> |
107 * <p> |
107 * <p> |
108 * A class can be mapped to a XML Schema simple type using the |
108 * A class can be mapped to a XML Schema simple type using the |
109 * <tt>@XmlValue</tt> annotation. For additional details and examples, |
109 * {@code @XmlValue} annotation. For additional details and examples, |
110 * see @{@link XmlValue} annotation type. |
110 * see @{@link XmlValue} annotation type. |
111 * <p> |
111 * <p> |
112 * The following table shows the mapping of the class to a XML Schema |
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: |
113 * complex type or simple type. The notational symbols used in the table are: |
114 * <ul> |
114 * <ul> |
115 * <li> {@literal ->} : represents a mapping </li> |
115 * <li> {@literal ->} : represents a mapping </li> |
116 * <li> [x]+ : one or more occurances of x </li> |
116 * <li> [x]+ : one or more occurances of x </li> |
117 * <li> [ <tt>@XmlValue</tt> property ]: JavaBean property annotated with |
117 * <li> [ {@code @XmlValue} property ]: JavaBean property annotated with |
118 * <tt>@XmlValue</tt></li> |
118 * {@code @XmlValue}</li> |
119 * <li> X : don't care |
119 * <li> X : don't care |
120 * </ul> |
120 * </ul> |
121 * <blockquote> |
121 * <blockquote> |
122 * <table summary="" border="1" cellpadding="4" cellspacing="3"> |
122 * <table summary="" border="1" cellpadding="4" cellspacing="3"> |
123 * <tbody> |
123 * <tbody> |
174 * |
174 * |
175 * <h3> Mapping an enum type </h3> |
175 * <h3> Mapping an enum type </h3> |
176 * |
176 * |
177 * An enum type maps to a XML schema simple type with enumeration |
177 * An enum type maps to a XML schema simple type with enumeration |
178 * facets. The following annotation elements are ignored since they |
178 * facets. The following annotation elements are ignored since they |
179 * are not meaningful: <tt>propOrder()</tt> , <tt>factoryMethod()</tt> , |
179 * are not meaningful: {@code propOrder()} , {@code factoryMethod()} , |
180 * <tt>factoryClass()</tt> . |
180 * {@code factoryClass()} . |
181 * |
181 * |
182 * <h3> Usage with other annotations </h3> |
182 * <h3> Usage with other annotations </h3> |
183 * <p> This annotation can be used with the following annotations: |
183 * <p> This annotation can be used with the following annotations: |
184 * {@link XmlRootElement}, {@link XmlAccessorOrder}, {@link XmlAccessorType}, |
184 * {@link XmlRootElement}, {@link XmlAccessorOrder}, {@link XmlAccessorType}, |
185 * {@link XmlEnum}. However, {@link |
185 * {@link XmlEnum}. However, {@link |
404 * JavaBean properties are listed is the order of XML Schema |
404 * JavaBean properties are listed is the order of XML Schema |
405 * elements to which the JavaBean properties are mapped. </p> |
405 * elements to which the JavaBean properties are mapped. </p> |
406 * <p> All of the JavaBean properties being mapped to XML Schema elements |
406 * <p> All of the JavaBean properties being mapped to XML Schema elements |
407 * must be listed. |
407 * must be listed. |
408 * <p> A JavaBean property or field listed in propOrder must not |
408 * <p> A JavaBean property or field listed in propOrder must not |
409 * be transient or annotated with <tt>@XmlTransient</tt>. |
409 * be transient or annotated with {@code @XmlTransient}. |
410 * <p> The default ordering of JavaBean properties is determined |
410 * <p> The default ordering of JavaBean properties is determined |
411 * by @{@link XmlAccessorOrder}. |
411 * by @{@link XmlAccessorOrder}. |
412 */ |
412 */ |
413 String[] propOrder() default {""}; |
413 String[] propOrder() default {""}; |
414 |
414 |
421 |
421 |
422 /** |
422 /** |
423 * Class containing a no-arg factory method for creating an |
423 * Class containing a no-arg factory method for creating an |
424 * instance of this class. The default is this class. |
424 * instance of this class. The default is this class. |
425 * |
425 * |
426 * <p>If <tt>factoryClass</tt> is DEFAULT.class and |
426 * <p>If {@code factoryClass} is DEFAULT.class and |
427 * <tt>factoryMethod</tt> is "", then there is no static factory |
427 * {@code factoryMethod} is "", then there is no static factory |
428 * method. |
428 * method. |
429 * |
429 * |
430 * <p>If <tt>factoryClass</tt> is DEFAULT.class and |
430 * <p>If {@code factoryClass} is DEFAULT.class and |
431 * <tt>factoryMethod</tt> is not "", then |
431 * {@code factoryMethod} is not "", then |
432 * <tt>factoryMethod</tt> is the name of a static factory method |
432 * {@code factoryMethod} is the name of a static factory method |
433 * in this class. |
433 * in this class. |
434 * |
434 * |
435 * <p>If <tt>factoryClass</tt> is not DEFAULT.class, then |
435 * <p>If {@code factoryClass} is not DEFAULT.class, then |
436 * <tt>factoryMethod</tt> must not be "" and must be the name of |
436 * {@code factoryMethod} must not be "" and must be the name of |
437 * a static factory method specified in <tt>factoryClass</tt>. |
437 * a static factory method specified in {@code factoryClass}. |
438 */ |
438 */ |
439 Class factoryClass() default DEFAULT.class; |
439 Class factoryClass() default DEFAULT.class; |
440 |
440 |
441 /** |
441 /** |
442 * Used in {@link XmlType#factoryClass()} to |
442 * Used in {@link XmlType#factoryClass()} to |