* Maps a class or an enum type to a XML Schema type. * *
Usage
*The {@code @XmlType} annnotation can be used with the following program * elements: *
See "Package Specification" in javax.xml.bind.package javadoc for * additional common information.
* ** A class maps to a XML Schema type. A class is a data container for * values represented by properties and fields. A schema type is a * data container for values represented by schema components within a * schema type's content model (e.g. model groups, attributes etc). *
To be mapped, a class must either have a public no-arg * constructor or a static no-arg factory method. The static factory * method can be specified in {@code factoryMethod()} and * {@code factoryClass()} annotation elements. The static factory * method or the no-arg constructor is used during unmarshalling to * create an instance of this class. If both are present, the static * factory method overrides the no-arg constructor. *
* A class maps to either a XML Schema complex type or a XML Schema simple * type. The XML Schema type is derived based on the * mapping of JavaBean properties and fields contained within the * class. The schema type to which the class is mapped can either be * named or anonymous. A class can be mapped to an anonymous schema * type by annotating the class with {@code @XmlType(name="")}. *
* Either a global element, local element or a local attribute can be * associated with an anonymous type as follows: *
* Mapping class to XML Schema simple type *
* A class can be mapped to a XML Schema simple type using the * {@code @XmlValue} annotation. For additional details and examples, * see @{@link XmlValue} annotation type. *
* The following table shows the mapping of the class to a XML Schema * complex type or simple type. The notational symbols used in the table are: *
** ** *
** * *Target *propOrder *ClassBody *ComplexType *SimpleType ** * *Class *{} *[property]+ {@literal ->} elements *complexcontent *
xs:all* * * *Class *non empty *[property]+ {@literal ->} elements *complexcontent *
xs:sequence* * * *Class *X *no property {@literal ->} element *complexcontent *
empty sequence* * * *Class *X *1 [{@code @XmlValue} property] {@literal &&} *
[property]+ {@literal ->} attributessimplecontent ** * * *Class *X *1 [{@code @XmlValue} property] {@literal &&} *
no properties {@literal ->} attribute* simpletype *
This annotation can be used with the following annotations: * {@link XmlRootElement}, {@link XmlAccessorOrder}, {@link XmlAccessorType}, * {@link XmlEnum}. However, {@link * XmlAccessorOrder} and {@link XmlAccessorType} are ignored when this * annotation is used on an enum type. * *
Example 1: Map a class to a complex type with * xs:sequence with a customized ordering of JavaBean properties. *
* *
* @XmlType(propOrder={"street", "city" , "state", "zip", "name" })
* public class USAddress {
* String getName() {..};
* void setName(String) {..};
*
* String getStreet() {..};
* void setStreet(String) {..};
*
* String getCity() {..};
* void setCity(String) {..};
*
* String getState() {..};
* void setState(String) {..};
*
* java.math.BigDecimal getZip() {..};
* void setZip(java.math.BigDecimal) {..};
* }
* {@code
*
*
*
*
*
* }
* Example 2: Map a class to a complex type with * xs:all
*
* @XmlType(propOrder={})
* public class USAddress { ...}
* {@code
*
*
*
*
*
*}
* Example 3: Map a class to a global element with an * anonymous type. *
*
* @XmlRootElement
* @XmlType(name="")
* public class USAddress { ...}
* {@code
*
*
*
*
*
*
*
*
* }
*
* Example 4: Map a property to a local element with * anonymous type. *
* //Example: Code fragment
* public class Invoice {
* USAddress addr;
* ...
* }
*
* @XmlType(name="")
* public class USAddress { ... }
* }
* {@code
*
*
*
*
*
*
*
* ...
*
*
* }
*
* Example 5: Map a property to an attribute with * anonymous type. * *
*
* //Example: Code fragment
* public class Item {
* public String name;
* @XmlAttribute
* public USPrice price;
* }
*
* // map class to anonymous simple type.
* @XmlType(name="")
* public class USPrice {
* @XmlValue
* public java.math.BigDecimal price;
* }
* {@code
*
*
*
*
*
*
*
*
*
*
* }
*
* Example 6: Define a factoryClass and factoryMethod * *
* @XmlType(name="USAddressType", factoryClass=USAddressFactory.class,
* factoryMethod="getUSAddress")
* public class USAddress {
*
* private String city;
* private String name;
* private String state;
* private String street;
* private int zip;
*
* public USAddress(String name, String street, String city,
* String state, int zip) {
* this.name = name;
* this.street = street;
* this.city = city;
* this.state = state;
* this.zip = zip;
* }
* }
*
* public class USAddressFactory {
* public static USAddress getUSAddress(){
* return new USAddress("Mark Baker", "23 Elm St",
* "Dayton", "OH", 90952);
* }
*
*
*
* Example 7: Define factoryMethod and use the default factoryClass * *
* @XmlType(name="USAddressType", factoryMethod="getNewInstance")
* public class USAddress {
*
* private String city;
* private String name;
* private String state;
* private String street;
* private int zip;
*
* private USAddress() {}
*
* public static USAddress getNewInstance(){
* return new USAddress();
* }
* }
*
*
* @author Sekhar Vajjhala, Sun Microsystems, Inc.
* @see XmlElement
* @see XmlAttribute
* @see XmlValue
* @see XmlSchema
* @since 1.6, JAXB 2.0
*/
@Retention(RUNTIME) @Target({TYPE})
public @interface XmlType {
/**
* Name of the XML Schema type which the class is mapped.
*/
String name() default "##default" ;
/**
* Specifies the order for XML Schema elements when class is
* mapped to a XML Schema complex type.
*
* Refer to the table for how the propOrder affects the * mapping of class
* *The propOrder is a list of names of JavaBean properties in * the class. Each name in the list is the name of a Java * identifier of the JavaBean property. The order in which * JavaBean properties are listed is the order of XML Schema * elements to which the JavaBean properties are mapped.
*All of the JavaBean properties being mapped to XML Schema elements * must be listed. *
A JavaBean property or field listed in propOrder must not * be transient or annotated with {@code @XmlTransient}. *
The default ordering of JavaBean properties is determined * by @{@link XmlAccessorOrder}. */ String[] propOrder() default {""}; /** * Name of the target namespace of the XML Schema type. By * default, this is the target namespace to which the package * containing the class is mapped. */ String namespace() default "##default" ; /** * Class containing a no-arg factory method for creating an * instance of this class. The default is this class. * *
If {@code factoryClass} is DEFAULT.class and * {@code factoryMethod} is "", then there is no static factory * method. * *
If {@code factoryClass} is DEFAULT.class and * {@code factoryMethod} is not "", then * {@code factoryMethod} is the name of a static factory method * in this class. * *
If {@code factoryClass} is not DEFAULT.class, then * {@code factoryMethod} must not be "" and must be the name of * a static factory method specified in {@code factoryClass}. */ Class factoryClass() default DEFAULT.class; /** * Used in {@link XmlType#factoryClass()} to * signal that either factory mehod is not used or * that it's in the class with this {@link XmlType} itself. */ static final class DEFAULT {} /** * Name of a no-arg factory method in the class specified in * {@code factoryClass} factoryClass(). * */ String factoryMethod() default ""; }