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 Schema 置換グループサポート

XML Schema では、XML 文書作成者は置換グループを使用して、スキーマのコンテンツモデルで静的に指定されていない XML 要素名を使用することができます。スキーマ派生コードは、「要素プロパティー」を使用して置換グループのサポートを提供します (5.5.5 節、JAXB 2.0 仕様の「要素プロパティー」)。要素プロパティーメソッドシグニチャーは、次の形式を取ります。

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

XmlElementDecl で注釈された要素ファクトリメソッドは、XML 要素名を含む JAXBElement インスタンスを作成するために使用されます。要素プロパティーに @XmlElementRef 注釈が存在することは、JavaBean プロパティー名からXML 要素名が派生するのでなく、JAXBElement インスタンスからの要素名が使用されることを意味します。

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

• コレクション項目型 (コレクションプロパティーの場合) またはプロパティー型 (単一値プロパティーの場合) が 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 タスクは、クラス階層内の 1 つのクラスに対応しています。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 Schema 置換グループサポート

次の例は、XML Schema 置換グループ用の注釈を示します。注釈と 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>
 

導入されたバージョン:

JAXB2.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 文書で置換された場合、置換要素に対する XmlElementDecl の要素名です。

type() が JAXBElement.class 以外の場合、XML 要素名は、型に対する XmlRootElement 注釈を使用して型に静的に関連付けられた XML 要素名です。型が XmlElementDecl で注釈されていない場合、エラーです。

type() が JAXBElement.class 以外の場合、この値は「」になります。

デフォルト:

""

name

public abstract String name

関連項目:

namespace()

デフォルト:

"##default"