javax.xml.bind.annotation
註釋型別 XmlElementRef

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlElementRef

將 JavaBean 屬性映射到派生於屬性型別的 XML 元素。

用法

@XmlElementRef 註釋可以與 JavaBean 屬性一起使用或在 XmlElementRefs 中使用。

此註釋將 XML 元素名稱與 JavaBean 屬性動態關聯起來。當 JavaBean 屬性使用 XmlElement 進行註釋時，XML 元素名稱以靜態方式派生於 JavaBean 屬性名稱。但是，在使用此註釋時，XML 元素名稱派生於運行時的 JavaBean 屬性型別的實例。

XML 網要替換組支持

XML 網要允許 XML 文檔作者使用 XML 元素名稱，這裡的名稱指沒有在使用替換組的網要的內容網要中靜態指定的名稱。網要派生程式碼為使用元素屬性的替換組提供了支持（請參閱 JAXB 2.0 規範的第 5.5.5 節：「元素屬性」）。元素屬性方法簽章的形式如下：

public void setTerm(JAXBElement<? extends Operator>);
public JAXBElement<? extends Operator> getTerm();
 

用 XmlElementDecl 註釋的元素處理器方法用於創建包含 XML 元素名稱的 JAXBElement 實例。元素屬性中出現 @XmlElementRef 註釋則表示使用取自 JAXBElement 實例的元素名稱，而不是從 JavaBean 屬性名稱中派生一個 XML 元素名稱。

• 如果集合條目型別（用於集合屬性）或屬性型別（用於單個賦值屬性）是 JAXBElement，則 @XmlElementRef}.name() 和 @XmlElementRef.namespace() 必須指向一個元素處理器方法，並在使用 @XmlRegistry 註釋的類別中存在一個 @XmlElementDecl 註釋（通常 ObjectFactory 類別由網要編譯器產生）：
  • @XmlElementDecl.name() 必須等於 @XmlElementRef.name()
  • @XmlElementDecl.namespace() 必須等於 @XmlElementRef.namespace()。
• 如果集合條目型別（用於集合屬性）或屬性型別（用於單個賦值屬性）不是 JAXBElement，則由屬性或欄位參考的型別必須是使用 XmlRootElement 註釋的。
• 此註釋可以與以下註釋一起使用：XmlElementWrapper 和 XmlJavaTypeAdapter。

有關其他公共資訊，請參閱 javax.xml.bind.package javadoc 中的“套件規範”。

範例 1：Ant 任務範例

以下 Java 類別層次結建構立了 Ant 建構文稿模型。Ant 任務對應於類別層次結構中的類別。Ant 任務的 XML 元素名稱由其對應類別上的 @XmlRootElement 註釋指示。

     @XmlRootElement(name="target")
     class Target {
         // The presence of @XmlElementRef indicates that the XML
         // element name will be derived from the @XmlRootElement 
         // annotation on the type (for e.g. "jar" for JarTask). 
         @XmlElementRef
         List<Task> tasks;
     }

     abstract class Task {
     }

     @XmlRootElement(name="jar")
     class JarTask extends Task {
         ...
     }

     @XmlRootElement(name="javac")
     class JavacTask extends Task {
         ...
     }

     <!-- XML Schema fragment -->
     <xs:element name="target" type="Target">
     <xs:complexType name="Target">
       <xs:sequence>
         <xs:choice maxOccurs="unbounded">
           <xs:element ref="jar">
           <xs:element ref="javac">
         </xs:choice>
       </xs:sequence>
     </xs:complexType>

 

因此下列程式碼片段

Target target = new Target();
target.tasks.add(new JarTask());
target.tasks.add(new JavacTask());
marshal(target);
 

將產生以下 XML 輸出：

     <target>
       <jar>
         ....
       </jar>
       <javac>
         ....
       </javac>
     </target>
 

有一個類別擴展了不具有 XmlRootElement 的 Task 並不是一個錯誤。但是這些類別將無法出現在 XML 實例中（因為它們沒有 XML 元素名稱）。

範例 2：XML 網要替換組支持

以下範例顯示用於 XML 網要替換組的註釋。註釋和 ObjectFactory 都派生於網要。

     @XmlElement
     class Math {
         //  The value of type()is 
         //  JAXBElement.class , which indicates the XML
         //  element name ObjectFactory - in general a class marked
         //  with @XmlRegistry. (See ObjectFactory below)
         //  
         //  The name() is "operator", a pointer to a
         // factory method annotated with a
         //  XmlElementDecl with the name "operator". Since
         //  "operator" is the head of a substitution group that
         //  contains elements "add" and "sub" elements, "operator"
         //  element can be substituted in an instance document by
         //  elements "add" or "sub". At runtime, JAXBElement
         //  instance contains the element name that has been
         //  substituted in the XML document.
         // 
         @XmlElementRef(type=JAXBElement.class,name="operator")
         JAXBElement<? extends Operator> term;
     }

     @XmlRegistry
     class ObjectFactory {
         @XmlElementDecl(name="operator")
         JAXBElement<Operator> createOperator(Operator o) {...}
         @XmlElementDecl(name="add",substitutionHeadName="operator")
         JAXBElement<Operator> createAdd(Operator o) {...}
         @XmlElementDecl(name="sub",substitutionHeadName="operator")
         JAXBElement<Operator> createSub(Operator o) {...}
     }

     class Operator {
         ...
     }
 

因此以下程式碼片段

Math m = new Math();
m.term = new ObjectFactory().createAdd(new Operator());
marshal(m);
 

將產生以下 XML 輸出：

<math>
<add>...</add>
</math>
 

從以下版本開始：

JAXB 2.0

另請參見：

XmlElementRefs

可選元素摘要

String	name
String	namespace 可以使用此參數和 name() 來確定 JavaBean 屬性的 XML 元素。
Class	type 被參考的 Java 型別。

type

public abstract Class type

被參考的 Java 型別。

如果該值為 DEFAULT.class，則可以從 JavaBean 屬性型別推導出該型別。

預設值：

javax.xml.bind.annotation.XmlElementRef.DEFAULT.class

namespace

public abstract String namespace

可以使用此參數和 name() 來確定 JavaBean 屬性的 XML 元素。

如果 type() 是 JAXBElement.class，那麼 namespace() 和 name() 指向帶有 XmlElementDecl 的處理器方法。XML 元素名稱是處理器方法的 XmlElementDecl 註釋的元素名稱，如果取自其替換組中的元素（替換組的頭元素）在 XML 文檔中已被替換，則 XML 元素名稱取自替換元素的 XmlElementDecl。

如果 type() 不是 JAXBElement.class，那麼 XML 元素名稱是與使用該型別上的 XmlRootElement 註釋的型別靜態關聯的 XML 元素名稱。如果沒有使用 XmlElementDecl 註釋該型別，那麼它是一個錯誤。

如果 type() 不是 JAXBElement.class，那麼此值必須是 ""。

預設值：

""

name

public abstract String name

另請參見：

namespace()

預設值：

"##default"