XmlType (Java EE 5)

Java EE API

previous page next page
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation Annotation Type XmlType

@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface XmlType

Implements: Annotation
Inner classes: XmlType.DEFAULT
@Retention(value=RUNTIME)
@Target(value=TYPE)

将类或枚举类型映射到 XML 模式类型。

使用

@XmlType 注释可以与以下程序元素一起使用：

  • 顶层类
  • 枚举类型

更多公共信息，请参见 javax.xml.bind.package javadoc 中的“包规范”。

映射一个类

将一个类映射到 XML 模式类型。类是通过属性和字段表示的值的数据容器。模式类型是一个数据容器，用于模式类型的内容模式中的模式组件（如模式组、属性等）所表示的值。

要被映射，类必须拥有一个不带参数的公共构造方法，或者一个静态的不带参数的工厂方法。静态工厂方法可以使用 factoryMethod() 和 factoryClass() 注释元素来指定。在解组过程中将使用静态工厂方法或不带参数的构造方法来创建此类的实例。如果两者同时存在，则静态工厂方法将重写不带参数的构造方法。

将类映射到 XML 模式复杂类型或 XML 模式简单类型。XML 模式类型是基于类中包含的 JavaBean 属性和字段的映射派生出来的。类将要映射到的模式类型可以是已命名的，也可以是匿名的。通过使用 @XmlType(name="") 对类进行注释，可以将该类映射到匿名模式类型。

全局元素、本地元素或本地属性都可以与匿名类型关联，如下所示：

  • 全局元素：通过使用 @XmlRootElement 对类进行注释，可以派生出一个匿名类型的全局元素。请参见下面的示例 3。
  • 本地元素： JavaBean 属性，引用使用 @XmlType(name="") 注释的类且映射到与匿名类型关联的某一元素。请参见下面的示例 4。
  • 属性： JavaBean 属性，引用使用 @XmlType(name="") 注释的类且映射到与匿名类型关联的某一属性。请参见下面的示例 5。
映射到 XML 模式复杂类型
  • 如果使用 @XmlType(name="") 对类进行注释，那么该类将被映射到匿名类型。否则将类名称映射到复杂类型名称。可以使用 XmlName() 注释元素来自定义名称。
  • 映射到元素的属性和字段将映射到复杂类型中的内容模式。可以使用注释元素 propOrder() 将内容模式自定义为 xs:all 或 xs:sequence，还可以使用该元素指定 xs:sequence 中 XML 元素的顺序。
  • 可以映射到复杂类型中的属性的属性和字段。
  • XML 模式类型的 targetnamespace 可以使用注释元素 namespace() 自定义。

将类映射到 XML 模式简单类型

可以使用 @XmlValue 注释将类映射到 XML 模式简单类型。有关其他详细信息和示例，请参见 @XmlValue 注释类型。

下表显示了类到 XML 模式复杂类型或简单类型的映射。表中使用的标志符号是：

  • -> : 代表一个映射
  • [x]+ :x 出现一次或多次
  • [ @XmlValue property ]:使用 @XmlValue 注释的 JavaBean 属性
  • X :任意
目标 propOrder ClassBody ComplexType SimpleType
类 {} [property]+ -> elements complexcontent
xs:all
类 non empty [property]+ -> elements complexcontent
xs:sequence
类 X no property -> element complexcontent
empty sequence
类 X 1 [ @XmlValue property] &&
[property]+ ->attributes		 simplecontent
类 X 1 [ @XmlValue property ]&&
no properties -> attribute		 simpletype

映射一个枚举类型

将枚举类型映射到带有 enumeration facet 的 XML 模式简单类型。由于没有意义，以下注释元素将被忽略：propOrder()、factoryMethod() 和 factoryClass()。

与其他注释一起使用的方法

此注释可与以下注释一起使用：XmlRootElement、XmlAccessorOrder、XmlAccessorType、XmlEnum。但是，当此注释用于枚举类型时，将忽略 XmlAccessorOrder 和 XmlAccessorType。

示例 1：将类映射到具有 xs:sequence 属性和自定义的 JavaBean 属性排序的复杂类型。 

   @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>

示例 2：将类映射到具有 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>

示例 3：将类映射到具有匿名类型的全局元素。 

   @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>

示例 4：将属性映射到具有匿名类型的本地元素。 

   //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>

示例 5：将属性映射到具有匿名类型的属性。 

     //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>

示例 6：定义 factoryClass 和 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);
  }

示例 7：定义 factoryMethod 并使用默认 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();
          }
      }
sinceJAXB2.0
version
en
$Revision: 1.20 $
See also javax.xml.bind.annotation.XmlElement, javax.xml.bind.annotation.XmlAttribute, javax.xml.bind.annotation.XmlValue, javax.xml.bind.annotation.XmlSchema
英文文档：

Maps a class or an enum type to a XML Schema type.

Usage

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

  • a top level class
  • an enum type

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Mapping a Class

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:

  • global element: A global element of an anonymous type can be derived by annotating the class with @XmlRootElement. See Example 3 below.
  • local element: A JavaBean property that references a class annotated with @XmlType(name="") and is mapped to the element associated with the anonymous type. See Example 4 below.
  • attribute: A JavaBean property that references a class annotated with @XmlType(name="") and is mapped to the attribute associated with the anonymous type. See Example 5 below.
Mapping to XML Schema Complex Type
  • If class is annotated with @XmlType(name="") , it is mapped to an anonymous type otherwise, the class name maps to a complex type name. The XmlName() annotation element can be used to customize the name.
  • Properties and fields that are mapped to elements are mapped to a content model within a complex type. The annotation element propOrder() can be used to customize the content model to be xs:all or xs:sequence. It is used for specifying the order of XML elements in xs:sequence.
  • Properties and fields can be mapped to attributes within the complex type.
  • The targetnamespace of the XML Schema type can be customized using the annotation element namespace().

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 @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:

  • -> : represents a mapping
  • [x]+ : one or more occurances of x
  • [ @XmlValue property ]: JavaBean property annotated with @XmlValue
  • X : don't care
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]+ ->attributes		 simplecontent
Class X 1 [ @XmlValue property ]&&
no properties -> attribute		 simpletype

Mapping an enum type

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

Usage with other annotations

This annotation can be used with the following annotations: XmlRootElement, XmlAccessorOrder, XmlAccessorType, XmlEnum. However, XmlAccessorOrder and 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();
          }
      }

Since:
JAXB2.0
Version:
$Revision: 1.20 $
Author:
Sekhar Vajjhala, Sun Microsystems, Inc.
See Also:
XmlElement, XmlAttribute, XmlValue, XmlSchema

Optional Element Summary
 Class factoryClass
          Class containing a no-arg factory method for creating an instance of this class.
 String factoryMethod
          Name of a no-arg factory method in the class specified in factoryClass factoryClass().
 String name
          Name of the XML Schema type which the class is mapped.
 String namespace
          Name of the target namespace of the XML Schema type.
 String[] propOrder
          Specifies the order for XML Schema elements when class is mapped to a XML Schema complex type.
 

abstract public String name()
类被映射到的 XML 模式类型名称。
英文文档：

name

public abstract String name
Name of the XML Schema type which the class is mapped.

Default:
"##default"

abstract public String[] propOrder()
在将类映射到 XML 模式复杂类型时，指定 XML 模式元素的顺序。

有关 propOrder 影响类映射的方式，请参见上表。

propOrder 是类中 JavaBean 属性的名称列表。列表中的每个名称都是 JavaBean 属性的 Java 标识符的名称。JavaBean 属性被列出的顺序是 JavaBean 属性映射到 XML 模式元素的顺序。

必须列出所有映射到 XML 模式元素的 JavaBean 属性。

以 propOrder 顺序列出的 JavaBean 属性或字段不得为 transient 或使用 @XmlTransient 注释。

JavaBean 属性的默认顺序由 @XmlAccessorOrder 确定。

英文文档：

propOrder

public abstract String[] propOrder
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 @XmlAccessorOrder.

Default:
""

abstract public String namespace()
XML 模式类型的目标名称空间名。默认情况下，这是包含类的包将被映射到的目标名称空间。
英文文档：

namespace

public abstract String namespace
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.

Default:
"##default"

abstract public Class<T> factoryClass()
包含用来创建此类实例的不带参数的工厂方法的类。默认值为此类。

如果 factoryClass 为 DEFAULT.class 且 factoryMethod 为 ""，则没有静态工厂方法。

如果 factoryClass 为 DEFAULT.class 且 factoryMethod 不为 ""，则 factoryMethod 是此类中静态工厂方法的名称。

如果 factoryClass 不是 DEFAULT.class，则 factoryMethod 不得为 ""，且必须是 factoryClass 中指定的静态工厂方法的名称。

英文文档：

factoryClass

public abstract Class factoryClass
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.

Default:
javax.xml.bind.annotation.XmlType.DEFAULT.class

abstract public String factoryMethod()
一个不带参数的构造方法的名称，该构造方法在 factoryClass factoryClass() 所指定的类。
英文文档：

factoryMethod

public abstract String factoryMethod
Name of a no-arg factory method in the class specified in factoryClass factoryClass().

Default:
""
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT
Submit a bug or feature

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.

一看就知道只有菜鸟才干这么无知的事啦。

PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正；若因此而造成任何损失请直接找人民主席，请勿与本人联系。谢谢！

previous page start next page