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