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 要素名を使用することができます。スキーマ派生コードは、要素プロパティー (JAXB 2.0 仕様のセクション 5.5.5「要素プロパティー」) を使用して置換グループのサポートを提供します。要素プロパティーメソッドシグニチャーは、次の形式を取ります。

     public void setTerm(JAXBElement);
     public JAXBElement 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。

追加の一般的な情報については、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 要素が決定されます。
boolean	required 要素宣言をカスタマイズして required にします。
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」

required

public abstract boolean required

要素宣言をカスタマイズして required にします。

required() が true の場合、JavaBean プロパティーは、「minOccurs="1"」のXML Schema 要素宣言にマップされます。maxOccurs は、単一値のプロパティーの場合は「1」、複数値のプロパティーの場合は「unbounded」です。

required() が false の場合、JavaBean プロパティーは、「minOccurs="0"」の XML Schema 要素宣言にマップされます。maxOccurs は、単一値のプロパティーの場合は「1」、複数値のプロパティーの場合は「unbounded」です。

JAXB 2.1 との互換性のため、XmlElement.required() のデフォルトが false であるにもかかわらず、このプロパティーのデフォルトは true です。

導入されたバージョン:

2.2

デフォルト:

true