注释类型 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="") 对类进行注释，可以将该类映射到匿名模式类型。

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

• 全局元素：通过使用 @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 :任意

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()。

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

此类可与以下注释一起使用： 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();
          }
      }
 

 

 

从以下版本开始：

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() 所指定的类。