JavaTM Platform
Standard Ed. 6

javax.xml.bind.annotation
注释类型 XmlType


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

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

用法

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

有关其他公共信息,请参阅 javax.xml.bind.package javadoc 中的“包规范”。

映射一个类

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

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

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

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

映射到 XML 模式复杂类型

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

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

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

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

映射一个枚举类型

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

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

此类可与以下注释一起使用: XmlRootElementXmlAccessorOrderXmlAccessorTypeXmlEnum。但是,当此注释用于枚举类型时,将忽略 XmlAccessorOrderXmlAccessorType

示例 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();
          }
      }
 

从以下版本开始:
JAXB2.0
另请参见:
XmlElement, XmlAttribute, XmlValue, XmlSchema

可选元素摘要
 Class factoryClass
          包含用来创建此类实例的不带参数的工厂方法的类。
 String factoryMethod
          一个不带参数的构造方法的名称,该构造方法在 factoryClass factoryClass() 所指定的类。
 String name
          类被映射到的 XML 模式类型名称。
 String namespace
          XML 模式类型的目标名称空间名。
 String[] propOrder
          在将类映射到 XML 模式复杂类型时,指定 XML 模式元素的顺序。
 

name

public abstract String name
类被映射到的 XML 模式类型名称。

默认值:
"##default"

propOrder

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

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

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

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

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

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

默认值:
""

namespace

public abstract String namespace
XML 模式类型的目标名称空间名。默认情况下,这是包含类的包将被映射到的目标名称空间。

默认值:
"##default"

factoryClass

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

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

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

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

默认值:
javax.xml.bind.annotation.XmlType.DEFAULT.class

factoryMethod

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

默认值:
""

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策