XmlType (Java 2 Platform SE 6)

概觀

軟體套件

類別

使用

階層樹

已過時

索引

說明

Java^TM 2 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="") 對類別進行註釋，可以將該類別映射到匿名網要型別。

全體元素、本地元素或本地屬性都可以與匿名型別關聯，如下所示：

全體元素：通過使用 @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() 所指定的類別。

預設值：: ""

概觀