@Retention(value=RUNTIME) @Target(value={FIELD,METHOD}) public @interface XmlElementRef
JavaBeanプロパティを、プロパティの型から派生したXML要素にマップします。
使用法
@XmlElementRef注釈は、JavaBeanプロパティで使用するか、XmlElementRefs内から使用できます。
この注釈は、XML要素名をJavaBeanプロパティに動的に関連付けます。 JavaBeanプロパティがXmlElementで注釈されている場合、XML要素名は静的にJavaBeanプロパティ名から派生します。 しかし、この注釈が使用される場合、XML要素名は実行時にJavaBeanプロパティの型のインスタンスから派生します。
public void setTerm(JAXBElement);
public JAXBElement getTerm();
XmlElementDeclで注釈された要素ファクトリ・メソッドは、XML要素名を含むJAXBElementインスタンスを作成するために使用されます。 要素プロパティに@XmlElementRef注釈が存在することは、JavaBeanプロパティ名からXML要素名が派生するのでなく、JAXBElementインスタンスからの要素名が使用されることを意味します。
使用には次の制約があります。
JAXBElementの場合、@XmlElementRef}.name()と@XmlElementRef.namespace()は、@XmlRegistryで注釈されたクラス(通常、スキーマ・コンパイラによって生成されるObjectFactoryクラス)内の@XmlElementDecl注釈を伴う要素ファクトリ・メソッドを示す必要があります。
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>
XmlElementRefspublic abstract Class type
値がDEFAULT.classの場合、型はJavaBeanプロパティの型から推定されます。
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以外の場合、この値は「」になります。
public abstract String name
namespace()public abstract boolean 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です。
バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。 そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2025, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Documentation Redistribution Policyも参照してください。