ohair@286: /* ohair@286: * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved. ohair@286: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. ohair@286: * ohair@286: * This code is free software; you can redistribute it and/or modify it ohair@286: * under the terms of the GNU General Public License version 2 only, as ohair@286: * published by the Free Software Foundation. Oracle designates this ohair@286: * particular file as subject to the "Classpath" exception as provided ohair@286: * by Oracle in the LICENSE file that accompanied this code. ohair@286: * ohair@286: * This code is distributed in the hope that it will be useful, but WITHOUT ohair@286: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or ohair@286: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License ohair@286: * version 2 for more details (a copy is included in the LICENSE file that ohair@286: * accompanied this code). ohair@286: * ohair@286: * You should have received a copy of the GNU General Public License version ohair@286: * 2 along with this work; if not, write to the Free Software Foundation, ohair@286: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. ohair@286: * ohair@286: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@286: * or visit www.oracle.com if you need additional information or have any ohair@286: * questions. ohair@286: */ ohair@286: ohair@286: package javax.xml.bind.annotation; ohair@286: ohair@286: import static java.lang.annotation.ElementType.TYPE; ohair@286: import java.lang.annotation.Retention; ohair@286: import static java.lang.annotation.RetentionPolicy.RUNTIME; ohair@286: import java.lang.annotation.Target; ohair@286: ohair@286: /** ohair@286: *
ohair@286: * Maps a class or an enum type to a XML Schema type. ohair@286: * ohair@286: *
Usage
ohair@286: *The @XmlType annnotation can be used with the following program ohair@286: * elements: ohair@286: *
See "Package Specification" in javax.xml.bind.package javadoc for ohair@286: * additional common information.
ohair@286: * ohair@286: *ohair@286: * A class maps to a XML Schema type. A class is a data container for ohair@286: * values represented by properties and fields. A schema type is a ohair@286: * data container for values represented by schema components within a ohair@286: * schema type's content model (e.g. model groups, attributes etc). ohair@286: *
To be mapped, a class must either have a public no-arg ohair@286: * constructor or a static no-arg factory method. The static factory ohair@286: * method can be specified in factoryMethod() and ohair@286: * factoryClass() annotation elements. The static factory ohair@286: * method or the no-arg constructor is used during unmarshalling to ohair@286: * create an instance of this class. If both are present, the static ohair@286: * factory method overrides the no-arg constructor. ohair@286: *
ohair@286: * A class maps to either a XML Schema complex type or a XML Schema simple ohair@286: * type. The XML Schema type is derived based on the ohair@286: * mapping of JavaBean properties and fields contained within the ohair@286: * class. The schema type to which the class is mapped can either be ohair@286: * named or anonymous. A class can be mapped to an anonymous schema ohair@286: * type by annotating the class with @XmlType(name=""). ohair@286: *
ohair@286: * Either a global element, local element or a local attribute can be ohair@286: * associated with an anonymous type as follows: ohair@286: *
ohair@286: * Mapping class to XML Schema simple type ohair@286: *
ohair@286: * A class can be mapped to a XML Schema simple type using the ohair@286: * @XmlValue annotation. For additional details and examples, ohair@286: * see @{@link XmlValue} annotation type. ohair@286: *
ohair@286: * The following table shows the mapping of the class to a XML Schema ohair@286: * complex type or simple type. The notational symbols used in the table are: ohair@286: *
ohair@286: *ohair@286: * ohair@286: *ohair@286: * ohair@286: *
ohair@286: *ohair@286: * ohair@286: * ohair@286: *Target ohair@286: *propOrder ohair@286: *ClassBody ohair@286: *ComplexType ohair@286: *SimpleType ohair@286: *ohair@286: * ohair@286: * ohair@286: *Class ohair@286: *{} ohair@286: *[property]+ -> elements ohair@286: *complexcontent ohair@286: *
xs:allohair@286: * ohair@286: * ohair@286: * ohair@286: *Class ohair@286: *non empty ohair@286: *[property]+ -> elements ohair@286: *complexcontent ohair@286: *
xs:sequenceohair@286: * ohair@286: * ohair@286: * ohair@286: *Class ohair@286: *X ohair@286: *no property -> element ohair@286: *complexcontent ohair@286: *
empty sequenceohair@286: * ohair@286: * ohair@286: * ohair@286: *Class ohair@286: *X ohair@286: *1 [ @XmlValue property] && ohair@286: *
[property]+ ohair@286: * ->attributessimplecontent ohair@286: *ohair@286: * ohair@286: * ohair@286: * ohair@286: *Class ohair@286: *X ohair@286: *1 [ @XmlValue property ]&& ohair@286: *
no properties ohair@286: * -> attributeohair@286: * simpletype ohair@286: *ohair@286: *
This annotation can be used with the following annotations: ohair@286: * {@link XmlRootElement}, {@link XmlAccessorOrder}, {@link XmlAccessorType}, ohair@286: * {@link XmlEnum}. However, {@link ohair@286: * XmlAccessorOrder} and {@link XmlAccessorType} are ignored when this ohair@286: * annotation is used on an enum type. ohair@286: * ohair@286: *
Example 1: Map a class to a complex type with ohair@286: * xs:sequence with a customized ordering of JavaBean properties. ohair@286: *
ohair@286: * ohair@286: *ohair@286: * @XmlType(propOrder={"street", "city" , "state", "zip", "name" }) ohair@286: * public class USAddress { ohair@286: * String getName() {..}; ohair@286: * void setName(String) {..}; ohair@286: * ohair@286: * String getStreet() {..}; ohair@286: * void setStreet(String) {..}; ohair@286: * ohair@286: * String getCity() {..}; ohair@286: * void setCity(String) {..}; ohair@286: * ohair@286: * String getState() {..}; ohair@286: * void setState(String) {..}; ohair@286: * ohair@286: * java.math.BigDecimal getZip() {..}; ohair@286: * void setZip(java.math.BigDecimal) {..}; ohair@286: * } ohair@286: * ohair@286: * <!-- XML Schema mapping for USAddress --> ohair@286: * <xs:complexType name="USAddress"> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="street" type="xs:string"/> ohair@286: * <xs:element name="city" type="xs:string"/> ohair@286: * <xs:element name="state" type="xs:string"/> ohair@286: * <xs:element name="zip" type="xs:decimal"/> ohair@286: * <xs:element name="name" type="xs:string"/> ohair@286: * </xs:all> ohair@286: * </xs:complexType> ohair@286: *ohair@286: *
Example 2: Map a class to a complex type with ohair@286: * xs:all
ohair@286: *ohair@286: * @XmlType(propOrder={}) ohair@286: * public class USAddress { ...} ohair@286: * ohair@286: * <!-- XML Schema mapping for USAddress --> ohair@286: * <xs:complexType name="USAddress"> ohair@286: * <xs:all> ohair@286: * <xs:element name="name" type="xs:string"/> ohair@286: * <xs:element name="street" type="xs:string"/> ohair@286: * <xs:element name="city" type="xs:string"/> ohair@286: * <xs:element name="state" type="xs:string"/> ohair@286: * <xs:element name="zip" type="xs:decimal"/> ohair@286: * </xs:sequence> ohair@286: * </xs:complexType> ohair@286: *ohair@286: *
Example 3: Map a class to a global element with an ohair@286: * anonymous type. ohair@286: *
ohair@286: *ohair@286: * @XmlRootElement ohair@286: * @XmlType(name="") ohair@286: * public class USAddress { ...} ohair@286: * ohair@286: * <!-- XML Schema mapping for USAddress --> ohair@286: * <xs:element name="USAddress"> ohair@286: * <xs:complexType> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="name" type="xs:string"/> ohair@286: * <xs:element name="street" type="xs:string"/> ohair@286: * <xs:element name="city" type="xs:string"/> ohair@286: * <xs:element name="state" type="xs:string"/> ohair@286: * <xs:element name="zip" type="xs:decimal"/> ohair@286: * </xs:sequence> ohair@286: * </xs:complexType> ohair@286: * </xs:element> ohair@286: *ohair@286: * ohair@286: *
Example 4: Map a property to a local element with ohair@286: * anonmyous type. ohair@286: *
ohair@286: * //Example: Code fragment ohair@286: * public class Invoice { ohair@286: * USAddress addr; ohair@286: * ... ohair@286: * } ohair@286: * ohair@286: * @XmlType(name="") ohair@286: * public class USAddress { ... } ohair@286: * } ohair@286: * ohair@286: * <!-- XML Schema mapping for USAddress --> ohair@286: * <xs:complexType name="Invoice"> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="addr"> ohair@286: * <xs:complexType> ohair@286: * <xs:element name="name", type="xs:string"/> ohair@286: * <xs:element name="city", type="xs:string"/> ohair@286: * <xs:element name="city" type="xs:string"/> ohair@286: * <xs:element name="state" type="xs:string"/> ohair@286: * <xs:element name="zip" type="xs:decimal"/> ohair@286: * </xs:complexType> ohair@286: * ... ohair@286: * </xs:sequence> ohair@286: * </xs:complexType> ohair@286: *ohair@286: * ohair@286: *
Example 5: Map a property to an attribute with ohair@286: * anonymous type. ohair@286: * ohair@286: *
ohair@286: * ohair@286: * //Example: Code fragment ohair@286: * public class Item { ohair@286: * public String name; ohair@286: * @XmlAttribute ohair@286: * public USPrice price; ohair@286: * } ohair@286: * ohair@286: * // map class to anonymous simple type. ohair@286: * @XmlType(name="") ohair@286: * public class USPrice { ohair@286: * @XmlValue ohair@286: * public java.math.BigDecimal price; ohair@286: * } ohair@286: * ohair@286: * <!-- Example: XML Schema fragment --> ohair@286: * <xs:complexType name="Item"> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="name" type="xs:string"/> ohair@286: * <xs:attribute name="price"> ohair@286: * <xs:simpleType> ohair@286: * <xs:restriction base="xs:decimal"/> ohair@286: * </xs:simpleType> ohair@286: * </xs:attribute> ohair@286: * </xs:sequence> ohair@286: * </xs:complexType> ohair@286: *ohair@286: * ohair@286: *
Example 6: Define a factoryClass and factoryMethod ohair@286: * ohair@286: *
ohair@286: * @XmlType(name="USAddressType", factoryClass=USAddressFactory.class, ohair@286: * factoryMethod="getUSAddress") ohair@286: * public class USAddress { ohair@286: * ohair@286: * private String city; ohair@286: * private String name; ohair@286: * private String state; ohair@286: * private String street; ohair@286: * private int zip; ohair@286: * ohair@286: * public USAddress(String name, String street, String city, ohair@286: * String state, int zip) { ohair@286: * this.name = name; ohair@286: * this.street = street; ohair@286: * this.city = city; ohair@286: * this.state = state; ohair@286: * this.zip = zip; ohair@286: * } ohair@286: * } ohair@286: * ohair@286: * public class USAddressFactory { ohair@286: * public static USAddress getUSAddress(){ ohair@286: * return new USAddress("Mark Baker", "23 Elm St", ohair@286: * "Dayton", "OH", 90952); ohair@286: * } ohair@286: * ohair@286: *ohair@286: * ohair@286: *
Example 7: Define factoryMethod and use the default factoryClass ohair@286: * ohair@286: *
ohair@286: * @XmlType(name="USAddressType", factoryMethod="getNewInstance") ohair@286: * public class USAddress { ohair@286: * ohair@286: * private String city; ohair@286: * private String name; ohair@286: * private String state; ohair@286: * private String street; ohair@286: * private int zip; ohair@286: * ohair@286: * private USAddress() {} ohair@286: * ohair@286: * public static USAddress getNewInstance(){ ohair@286: * return new USAddress(); ohair@286: * } ohair@286: * } ohair@286: *ohair@286: * ohair@286: * @author Sekhar Vajjhala, Sun Microsystems, Inc. ohair@286: * @see XmlElement ohair@286: * @see XmlAttribute ohair@286: * @see XmlValue ohair@286: * @see XmlSchema ohair@286: * @since JAXB2.0 ohair@286: */ ohair@286: ohair@286: @Retention(RUNTIME) @Target({TYPE}) ohair@286: public @interface XmlType { ohair@286: /** ohair@286: * Name of the XML Schema type which the class is mapped. ohair@286: */ ohair@286: String name() default "##default" ; ohair@286: ohair@286: /** ohair@286: * Specifies the order for XML Schema elements when class is ohair@286: * mapped to a XML Schema complex type. ohair@286: * ohair@286: *
Refer to the table for how the propOrder affects the ohair@286: * mapping of class
ohair@286: * ohair@286: *The propOrder is a list of names of JavaBean properties in ohair@286: * the class. Each name in the list is the name of a Java ohair@286: * identifier of the JavaBean property. The order in which ohair@286: * JavaBean properties are listed is the order of XML Schema ohair@286: * elements to which the JavaBean properties are mapped.
ohair@286: *All of the JavaBean properties being mapped to XML Schema elements ohair@286: * must be listed. ohair@286: *
A JavaBean property or field listed in propOrder must not ohair@286: * be transient or annotated with @XmlTransient. ohair@286: *
The default ordering of JavaBean properties is determined ohair@286: * by @{@link XmlAccessorOrder}. ohair@286: */ ohair@286: String[] propOrder() default {""}; ohair@286: ohair@286: /** ohair@286: * Name of the target namespace of the XML Schema type. By ohair@286: * default, this is the target namespace to which the package ohair@286: * containing the class is mapped. ohair@286: */ ohair@286: String namespace() default "##default" ; ohair@286: ohair@286: /** ohair@286: * Class containing a no-arg factory method for creating an ohair@286: * instance of this class. The default is this class. ohair@286: * ohair@286: *
If factoryClass is DEFAULT.class and ohair@286: * factoryMethod is "", then there is no static factory ohair@286: * method. ohair@286: * ohair@286: *
If factoryClass is DEFAULT.class and ohair@286: * factoryMethod is not "", then ohair@286: * factoryMethod is the name of a static factory method ohair@286: * in this class. ohair@286: * ohair@286: *
If factoryClass is not DEFAULT.class, then ohair@286: * factoryMethod must not be "" and must be the name of ohair@286: * a static factory method specified in factoryClass. ohair@286: */ ohair@286: Class factoryClass() default DEFAULT.class; ohair@286: ohair@286: /** ohair@286: * Used in {@link XmlType#factoryClass()} to ohair@286: * signal that either factory mehod is not used or ohair@286: * that it's in the class with this {@link XmlType} itself. ohair@286: */ ohair@286: static final class DEFAULT {} ohair@286: ohair@286: /** ohair@286: * Name of a no-arg factory method in the class specified in ohair@286: * factoryClass factoryClass(). ohair@286: * ohair@286: */ ohair@286: String factoryMethod() default ""; ohair@286: }