aoqi@0: /* aoqi@0: * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved. aoqi@0: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. aoqi@0: * aoqi@0: * This code is free software; you can redistribute it and/or modify it aoqi@0: * under the terms of the GNU General Public License version 2 only, as aoqi@0: * published by the Free Software Foundation. Oracle designates this aoqi@0: * particular file as subject to the "Classpath" exception as provided aoqi@0: * by Oracle in the LICENSE file that accompanied this code. aoqi@0: * aoqi@0: * This code is distributed in the hope that it will be useful, but WITHOUT aoqi@0: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or aoqi@0: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License aoqi@0: * version 2 for more details (a copy is included in the LICENSE file that aoqi@0: * accompanied this code). aoqi@0: * aoqi@0: * You should have received a copy of the GNU General Public License version aoqi@0: * 2 along with this work; if not, write to the Free Software Foundation, aoqi@0: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. aoqi@0: * aoqi@0: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA aoqi@0: * or visit www.oracle.com if you need additional information or have any aoqi@0: * questions. aoqi@0: */ aoqi@0: aoqi@0: package javax.xml.bind.annotation; aoqi@0: aoqi@0: import static java.lang.annotation.ElementType.TYPE; aoqi@0: import java.lang.annotation.Retention; aoqi@0: import static java.lang.annotation.RetentionPolicy.RUNTIME; aoqi@0: import java.lang.annotation.Target; aoqi@0: aoqi@0: /** aoqi@0: *

aoqi@0: * Maps a class or an enum type to a XML Schema type. aoqi@0: * aoqi@0: *

Usage

aoqi@0: *

The @XmlType annnotation can be used with the following program aoqi@0: * elements: aoqi@0: *

aoqi@0: * aoqi@0: *

See "Package Specification" in javax.xml.bind.package javadoc for aoqi@0: * additional common information.

aoqi@0: * aoqi@0: *

Mapping a Class

aoqi@0: *

aoqi@0: * A class maps to a XML Schema type. A class is a data container for aoqi@0: * values represented by properties and fields. A schema type is a aoqi@0: * data container for values represented by schema components within a aoqi@0: * schema type's content model (e.g. model groups, attributes etc). aoqi@0: *

To be mapped, a class must either have a public no-arg aoqi@0: * constructor or a static no-arg factory method. The static factory aoqi@0: * method can be specified in factoryMethod() and aoqi@0: * factoryClass() annotation elements. The static factory aoqi@0: * method or the no-arg constructor is used during unmarshalling to aoqi@0: * create an instance of this class. If both are present, the static aoqi@0: * factory method overrides the no-arg constructor. aoqi@0: *

aoqi@0: * A class maps to either a XML Schema complex type or a XML Schema simple aoqi@0: * type. The XML Schema type is derived based on the aoqi@0: * mapping of JavaBean properties and fields contained within the aoqi@0: * class. The schema type to which the class is mapped can either be aoqi@0: * named or anonymous. A class can be mapped to an anonymous schema aoqi@0: * type by annotating the class with @XmlType(name=""). aoqi@0: *

aoqi@0: * Either a global element, local element or a local attribute can be aoqi@0: * associated with an anonymous type as follows: aoqi@0: *

aoqi@0: * Mapping to XML Schema Complex Type aoqi@0: * aoqi@0: * aoqi@0: *

aoqi@0: * Mapping class to XML Schema simple type aoqi@0: *

aoqi@0: * A class can be mapped to a XML Schema simple type using the aoqi@0: * @XmlValue annotation. For additional details and examples, aoqi@0: * see @{@link XmlValue} annotation type. aoqi@0: *

aoqi@0: * The following table shows the mapping of the class to a XML Schema aoqi@0: * complex type or simple type. The notational symbols used in the table are: aoqi@0: *

aoqi@0: *
aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: *
TargetpropOrderClassBodyComplexTypeSimpleType
Class{}[property]+ -> elementscomplexcontent
xs:all
Classnon empty[property]+ -> elementscomplexcontent
xs:sequence
ClassXno property -> elementcomplexcontent
empty sequence
ClassX1 [ @XmlValue property] &&
[property]+ aoqi@0: * ->attributes		simplecontent
ClassX1 [ @XmlValue property ]&&
no properties aoqi@0: * -> attribute		 simpletype
aoqi@0: *
aoqi@0: * aoqi@0: *

Mapping an enum type

aoqi@0: * aoqi@0: * An enum type maps to a XML schema simple type with enumeration aoqi@0: * facets. The following annotation elements are ignored since they aoqi@0: * are not meaningful: propOrder() , factoryMethod() , aoqi@0: * factoryClass() . aoqi@0: * aoqi@0: *

Usage with other annotations

aoqi@0: *

This annotation can be used with the following annotations: aoqi@0: * {@link XmlRootElement}, {@link XmlAccessorOrder}, {@link XmlAccessorType}, aoqi@0: * {@link XmlEnum}. However, {@link aoqi@0: * XmlAccessorOrder} and {@link XmlAccessorType} are ignored when this aoqi@0: * annotation is used on an enum type. aoqi@0: * aoqi@0: *

Example 1: Map a class to a complex type with aoqi@0: * xs:sequence with a customized ordering of JavaBean properties. aoqi@0: *

aoqi@0: * aoqi@0: * 
aoqi@0:  *   @XmlType(propOrder={"street", "city" , "state", "zip", "name" })
aoqi@0:  *   public class USAddress {
aoqi@0:  *     String getName() {..};
aoqi@0:  *     void setName(String) {..};
aoqi@0:  *
aoqi@0:  *     String getStreet() {..};
aoqi@0:  *     void setStreet(String) {..};
aoqi@0:  *
aoqi@0:  *     String getCity() {..};
aoqi@0:  *     void setCity(String) {..};
aoqi@0:  *
aoqi@0:  *     String getState() {..};
aoqi@0:  *     void setState(String) {..};
aoqi@0:  *
aoqi@0:  *     java.math.BigDecimal getZip() {..};
aoqi@0:  *     void setZip(java.math.BigDecimal) {..};
aoqi@0:  *   }
aoqi@0:  *
aoqi@0:  *   <!-- XML Schema mapping for USAddress -->
aoqi@0:  *   <xs:complexType name="USAddress">
aoqi@0:  *     <xs:sequence>
aoqi@0:  *       <xs:element name="street" type="xs:string"/>
aoqi@0:  *       <xs:element name="city" type="xs:string"/>
aoqi@0:  *       <xs:element name="state" type="xs:string"/>
aoqi@0:  *       <xs:element name="zip" type="xs:decimal"/>
aoqi@0:  *       <xs:element name="name" type="xs:string"/>
aoqi@0:  *     </xs:all>
aoqi@0:  *   </xs:complexType>
aoqi@0:  *
aoqi@0: *

Example 2: Map a class to a complex type with aoqi@0: * xs:all

aoqi@0: * 
aoqi@0:  * @XmlType(propOrder={})
aoqi@0:  * public class USAddress { ...}
aoqi@0:  *
aoqi@0:  * <!-- XML Schema mapping for USAddress -->
aoqi@0:  * <xs:complexType name="USAddress">
aoqi@0:  *   <xs:all>
aoqi@0:  *     <xs:element name="name" type="xs:string"/>
aoqi@0:  *     <xs:element name="street" type="xs:string"/>
aoqi@0:  *     <xs:element name="city" type="xs:string"/>
aoqi@0:  *     <xs:element name="state" type="xs:string"/>
aoqi@0:  *     <xs:element name="zip" type="xs:decimal"/>
aoqi@0:  *   </xs:sequence>
aoqi@0:  * </xs:complexType>
aoqi@0:  *
aoqi@0: *

Example 3: Map a class to a global element with an aoqi@0: * anonymous type. aoqi@0: *

aoqi@0: * 
aoqi@0:  *   @XmlRootElement
aoqi@0:  *   @XmlType(name="")
aoqi@0:  *   public class USAddress { ...}
aoqi@0:  *
aoqi@0:  *   <!-- XML Schema mapping for USAddress -->
aoqi@0:  *   <xs:element name="USAddress">
aoqi@0:  *     <xs:complexType>
aoqi@0:  *       <xs:sequence>
aoqi@0:  *         <xs:element name="name" type="xs:string"/>
aoqi@0:  *         <xs:element name="street" type="xs:string"/>
aoqi@0:  *         <xs:element name="city" type="xs:string"/>
aoqi@0:  *         <xs:element name="state" type="xs:string"/>
aoqi@0:  *         <xs:element name="zip" type="xs:decimal"/>
aoqi@0:  *       </xs:sequence>
aoqi@0:  *     </xs:complexType>
aoqi@0:  *   </xs:element>
aoqi@0:  *
aoqi@0: * aoqi@0: *

Example 4: Map a property to a local element with aoqi@0: * anonmyous type. aoqi@0: * 

aoqi@0:  *   //Example: Code fragment
aoqi@0:  *   public class Invoice {
aoqi@0:  *       USAddress addr;
aoqi@0:  *           ...
aoqi@0:  *       }
aoqi@0:  *
aoqi@0:  *   @XmlType(name="")
aoqi@0:  *   public class USAddress { ... }
aoqi@0:  *   }
aoqi@0:  *
aoqi@0:  *   <!-- XML Schema mapping for USAddress -->
aoqi@0:  *   <xs:complexType name="Invoice">
aoqi@0:  *     <xs:sequence>
aoqi@0:  *       <xs:element name="addr">
aoqi@0:  *         <xs:complexType>
aoqi@0:  *           <xs:element name="name", type="xs:string"/>
aoqi@0:  *           <xs:element name="city", type="xs:string"/>
aoqi@0:  *           <xs:element name="city" type="xs:string"/>
aoqi@0:  *           <xs:element name="state" type="xs:string"/>
aoqi@0:  *           <xs:element name="zip" type="xs:decimal"/>
aoqi@0:  *         </xs:complexType>
aoqi@0:  *       ...
aoqi@0:  *     </xs:sequence>
aoqi@0:  *   </xs:complexType>
aoqi@0:  *
aoqi@0: * aoqi@0: *

Example 5: Map a property to an attribute with aoqi@0: * anonymous type. aoqi@0: * aoqi@0: * 

aoqi@0:  *
aoqi@0:  *     //Example: Code fragment
aoqi@0:  *     public class Item {
aoqi@0:  *         public String name;
aoqi@0:  *         @XmlAttribute
aoqi@0:  *         public USPrice price;
aoqi@0:  *     }
aoqi@0:  *
aoqi@0:  *     // map class to anonymous simple type.
aoqi@0:  *     @XmlType(name="")
aoqi@0:  *     public class USPrice {
aoqi@0:  *         @XmlValue
aoqi@0:  *         public java.math.BigDecimal price;
aoqi@0:  *     }
aoqi@0:  *
aoqi@0:  *     <!-- Example: XML Schema fragment -->
aoqi@0:  *     <xs:complexType name="Item">
aoqi@0:  *       <xs:sequence>
aoqi@0:  *         <xs:element name="name" type="xs:string"/>
aoqi@0:  *         <xs:attribute name="price">
aoqi@0:  *           <xs:simpleType>
aoqi@0:  *             <xs:restriction base="xs:decimal"/>
aoqi@0:  *           </xs:simpleType>
aoqi@0:  *         </xs:attribute>
aoqi@0:  *       </xs:sequence>
aoqi@0:  *     </xs:complexType>
aoqi@0:  *
aoqi@0: * aoqi@0: *

Example 6: Define a factoryClass and factoryMethod aoqi@0: * aoqi@0: * 

aoqi@0:  *      @XmlType(name="USAddressType", factoryClass=USAddressFactory.class,
aoqi@0:  *      factoryMethod="getUSAddress")
aoqi@0:  *      public class USAddress {
aoqi@0:  *
aoqi@0:  *          private String city;
aoqi@0:  *          private String name;
aoqi@0:  *          private String state;
aoqi@0:  *          private String street;
aoqi@0:  *          private int    zip;
aoqi@0:  *
aoqi@0:  *      public USAddress(String name, String street, String city,
aoqi@0:  *          String state, int zip) {
aoqi@0:  *          this.name = name;
aoqi@0:  *          this.street = street;
aoqi@0:  *          this.city = city;
aoqi@0:  *          this.state = state;
aoqi@0:  *          this.zip = zip;
aoqi@0:  *      }
aoqi@0:  *  }
aoqi@0:  *
aoqi@0:  *  public class USAddressFactory {
aoqi@0:  *      public static USAddress getUSAddress(){
aoqi@0:  *       return new USAddress("Mark Baker", "23 Elm St",
aoqi@0:  *          "Dayton", "OH", 90952);
aoqi@0:  *  }
aoqi@0:  *
aoqi@0:  *
aoqi@0: * aoqi@0: *

Example 7: Define factoryMethod and use the default factoryClass aoqi@0: * aoqi@0: * 

aoqi@0:  *      @XmlType(name="USAddressType", factoryMethod="getNewInstance")
aoqi@0:  *      public class USAddress {
aoqi@0:  *
aoqi@0:  *          private String city;
aoqi@0:  *          private String name;
aoqi@0:  *          private String state;
aoqi@0:  *          private String street;
aoqi@0:  *          private int    zip;
aoqi@0:  *
aoqi@0:  *          private USAddress() {}
aoqi@0:  *
aoqi@0:  *          public static USAddress getNewInstance(){
aoqi@0:  *              return new USAddress();
aoqi@0:  *          }
aoqi@0:  *      }
aoqi@0:  *
aoqi@0: * aoqi@0: * @author Sekhar Vajjhala, Sun Microsystems, Inc. aoqi@0: * @see XmlElement aoqi@0: * @see XmlAttribute aoqi@0: * @see XmlValue aoqi@0: * @see XmlSchema aoqi@0: * @since JAXB2.0 aoqi@0: */ aoqi@0: aoqi@0: @Retention(RUNTIME) @Target({TYPE}) aoqi@0: public @interface XmlType { aoqi@0: /** aoqi@0: * Name of the XML Schema type which the class is mapped. aoqi@0: */ aoqi@0: String name() default "##default" ; aoqi@0: aoqi@0: /** aoqi@0: * Specifies the order for XML Schema elements when class is aoqi@0: * mapped to a XML Schema complex type. aoqi@0: * aoqi@0: *

Refer to the table for how the propOrder affects the aoqi@0: * mapping of class

aoqi@0: * aoqi@0: *

The propOrder is a list of names of JavaBean properties in aoqi@0: * the class. Each name in the list is the name of a Java aoqi@0: * identifier of the JavaBean property. The order in which aoqi@0: * JavaBean properties are listed is the order of XML Schema aoqi@0: * elements to which the JavaBean properties are mapped.

aoqi@0: *

All of the JavaBean properties being mapped to XML Schema elements aoqi@0: * must be listed. aoqi@0: *

A JavaBean property or field listed in propOrder must not aoqi@0: * be transient or annotated with @XmlTransient. aoqi@0: *

The default ordering of JavaBean properties is determined aoqi@0: * by @{@link XmlAccessorOrder}. aoqi@0: */ aoqi@0: String[] propOrder() default {""}; aoqi@0: aoqi@0: /** aoqi@0: * Name of the target namespace of the XML Schema type. By aoqi@0: * default, this is the target namespace to which the package aoqi@0: * containing the class is mapped. aoqi@0: */ aoqi@0: String namespace() default "##default" ; aoqi@0: aoqi@0: /** aoqi@0: * Class containing a no-arg factory method for creating an aoqi@0: * instance of this class. The default is this class. aoqi@0: * aoqi@0: *

If factoryClass is DEFAULT.class and aoqi@0: * factoryMethod is "", then there is no static factory aoqi@0: * method. aoqi@0: * aoqi@0: *

If factoryClass is DEFAULT.class and aoqi@0: * factoryMethod is not "", then aoqi@0: * factoryMethod is the name of a static factory method aoqi@0: * in this class. aoqi@0: * aoqi@0: *

If factoryClass is not DEFAULT.class, then aoqi@0: * factoryMethod must not be "" and must be the name of aoqi@0: * a static factory method specified in factoryClass. aoqi@0: */ aoqi@0: Class factoryClass() default DEFAULT.class; aoqi@0: aoqi@0: /** aoqi@0: * Used in {@link XmlType#factoryClass()} to aoqi@0: * signal that either factory mehod is not used or aoqi@0: * that it's in the class with this {@link XmlType} itself. aoqi@0: */ aoqi@0: static final class DEFAULT {} aoqi@0: aoqi@0: /** aoqi@0: * Name of a no-arg factory method in the class specified in aoqi@0: * factoryClass factoryClass(). aoqi@0: * aoqi@0: */ aoqi@0: String factoryMethod() default ""; aoqi@0: }