-
@Retention(RUNTIME) @Target({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<? 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
。
追加の一般的な情報については、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) // // Thename()
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>
- 導入されたバージョン:
- 1.6, JAXB 2.0
- 関連項目:
XmlElementRefs
- コレクション・アイテム・タイプ(コレクション・プロパティの場合)またはプロパティ型(単一値プロパティの場合)が
-
-
要素の詳細
-
type
Class type
参照されるJava型です。値がDEFAULT.classの場合、型はJavaBeanプロパティの型から推定されます。
- デフォルト:
- javax.xml.bind.annotation.XmlElementRef.DEFAULT.class
-
-
-
namespace
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
String name
- 関連項目:
namespace()
- デフォルト:
- 「##default」
-
-
-
required
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
です。- 導入されたバージョン:
- 1.7, JAXB 2.2
- デフォルト:
- true
-
-