+ * Maps a class or an enum type to a XML Schema type. + * + *
Usage
+ *The @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 factoryMethod() and + * 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 @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 + * @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]+ -> elements + *complexcontent + *
xs:all+ * + * + * + *Class + *non empty + *[property]+ -> elements + *complexcontent + *
xs:sequence+ * + * + * + *Class + *X + *no property -> element + *complexcontent + *
empty sequence+ * + * + * + *Class + *X + *1 [ @XmlValue property] && + *
[property]+ + * ->attributessimplecontent + *+ * + * + * + *Class + *X + *1 [ @XmlValue property ]&& + *
no properties + * -> 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) {..};
+ * }
+ *
+ * <!-- XML Schema mapping for USAddress -->
+ * <xs:complexType name="USAddress">
+ * <xs:sequence>
+ * <xs:element name="street" type="xs:string"/>
+ * <xs:element name="city" type="xs:string"/>
+ * <xs:element name="state" type="xs:string"/>
+ * <xs:element name="zip" type="xs:decimal"/>
+ * <xs:element name="name" type="xs:string"/>
+ * </xs:all>
+ * </xs:complexType>
+ *
+ * Example 2: Map a class to a complex type with + * xs:all
+ *
+ * @XmlType(propOrder={})
+ * public class USAddress { ...}
+ *
+ * <!-- XML Schema mapping for USAddress -->
+ * <xs:complexType name="USAddress">
+ * <xs:all>
+ * <xs:element name="name" type="xs:string"/>
+ * <xs:element name="street" type="xs:string"/>
+ * <xs:element name="city" type="xs:string"/>
+ * <xs:element name="state" type="xs:string"/>
+ * <xs:element name="zip" type="xs:decimal"/>
+ * </xs:sequence>
+ * </xs:complexType>
+ *
+ * Example 3: Map a class to a global element with an + * anonymous type. + *
+ *
+ * @XmlRootElement
+ * @XmlType(name="")
+ * public class USAddress { ...}
+ *
+ * <!-- XML Schema mapping for USAddress -->
+ * <xs:element name="USAddress">
+ * <xs:complexType>
+ * <xs:sequence>
+ * <xs:element name="name" type="xs:string"/>
+ * <xs:element name="street" type="xs:string"/>
+ * <xs:element name="city" type="xs:string"/>
+ * <xs:element name="state" type="xs:string"/>
+ * <xs:element name="zip" type="xs:decimal"/>
+ * </xs:sequence>
+ * </xs:complexType>
+ * </xs:element>
+ *
+ *
+ * Example 4: Map a property to a local element with + * anonmyous type. + *
+ * //Example: Code fragment
+ * public class Invoice {
+ * USAddress addr;
+ * ...
+ * }
+ *
+ * @XmlType(name="")
+ * public class USAddress { ... }
+ * }
+ *
+ * <!-- XML Schema mapping for USAddress -->
+ * <xs:complexType name="Invoice">
+ * <xs:sequence>
+ * <xs:element name="addr">
+ * <xs:complexType>
+ * <xs:element name="name", type="xs:string"/>
+ * <xs:element name="city", type="xs:string"/>
+ * <xs:element name="city" type="xs:string"/>
+ * <xs:element name="state" type="xs:string"/>
+ * <xs:element name="zip" type="xs:decimal"/>
+ * </xs:complexType>
+ * ...
+ * </xs:sequence>
+ * </xs:complexType>
+ *
+ *
+ * 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;
+ * }
+ *
+ * <!-- Example: XML Schema fragment -->
+ * <xs:complexType name="Item">
+ * <xs:sequence>
+ * <xs:element name="name" type="xs:string"/>
+ * <xs:attribute name="price">
+ * <xs:simpleType>
+ * <xs:restriction base="xs:decimal"/>
+ * </xs:simpleType>
+ * </xs:attribute>
+ * </xs:sequence>
+ * </xs:complexType>
+ *
+ *
+ * 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 JAXB2.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 @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 factoryClass is DEFAULT.class and + * factoryMethod is "", then there is no static factory + * method. + * + *
If factoryClass is DEFAULT.class and + * factoryMethod is not "", then + * factoryMethod is the name of a static factory method + * in this class. + * + *
If factoryClass is not DEFAULT.class, then + * factoryMethod must not be "" and must be the name of + * a static factory method specified in 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 + * factoryClass factoryClass(). + * + */ + String factoryMethod() default ""; +}