@RetentionSE(RUNTIMESE)
@TargetSE({FIELDSE,METHODSE})
public @interface XmlElementRef

JavaBean プロパティをプロパティの型から派生した XML 要素にマップします。

使用方法

@XmlElementRef アノテーションは、JavaBean プロパティとともに、または XmlElementRefs 内から使用できます。

このアノテーションは、XML 要素名を JavaBean プロパティに動的に関連付けます。JavaBean プロパティに XmlElement のアノテーションが付けられている場合、XML 要素名は JavaBean プロパティ名から静的に派生します。ただし、このアノテーションを使用する場合、XML エレメント名は、実行時に JavaBean プロパティの型のインスタンスから派生します。

XML スキーマ置換グループのサポート

XML スキーマを使用すると、XML ドキュメントの作成者は、置換グループを使用してスキーマのコンテンツモデルで静的に指定されていない XML 要素名を使用できます。スキーマ派生コードは、 要素プロパティを使用した置換グループのサポートを提供します（セクション 5.5.5、Jakarta XML Binding 仕様の「要素プロパティ」）。要素プロパティメソッドのシグネチャーは次の形式です。

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

XmlElementDecl アノテーションが付けられた要素ファクトリメソッドは、XML 要素名を含む JAXBElement インスタンスを作成するために使用されます。要素プロパティに @XmlElementRef アノテーションが存在することは、JavaBean プロパティ名から XML 要素名を取得する代わりに、JAXBElement インスタンスからの要素名が使用されていることを示します。

使用箇所には、次の制約があります。

• コレクションアイテム型（コレクションプロパティの場合）またはプロパティ型（単一値プロパティの場合）が JAXBElement の場合、@XmlElementRef.name() および @XmlElementRef.namespace() は、@XmlRegistry アノテーションが付けられたクラス（通常はスキーマによって生成された ObjectFactory クラス）内の @XmlElementDecl アノテーションを持つ要素ファクトリメソッドを指す必要があります。コンパイラー）:
  • @XmlElementDecl.name() は @XmlElementRef.name() と等しくなければなりません
  • @XmlElementDecl.namespace() は @XmlElementRef.namespace() と等しくなければなりません。
• コレクションアイテム型（コレクションプロパティの場合）またはプロパティ型（単一値プロパティの場合）が JAXBElement でない場合、プロパティまたはフィールドによって参照される型には XmlRootElement アノテーションを付ける必要があります。
• このアノテーションは、XmlElementWrapper、XmlJavaTypeAdapter のアノテーションとともに使用できます。

追加の共通情報については、jakarta.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>