javax.xml.bind.annotation

Annotation Type XmlElementRef

@Retention(value=RUNTIME)
 @Target(value={字段,METHOD})
public @interface XmlElementRef

将JavaBean属性映射到从属性类型派生的XML元素。

用法

@XmlElementRef注释可以使用JavaBean属性或从XmlElementRefs

此注释将XML元素名称与JavaBean属性动态关联。 当JavaBean属性用XmlElement注释时，XML元素名称是从JavaBean属性名称静态派生的。 但是，当使用此注释时，XML元素名称将在运行时从JavaBean属性类型的实例派生。

支持XML Schema替换组

XML Schema允许XML文档作者使用未使用替换组在模式的内容模型中静态指定的XML元素名称。 Schema派生代码使用元素属性 （第5.5.5节“JAXB 2.0规范的”元素属性“）支持替换组。 元素属性方法签名的格式如下：

  public void setTerm(JAXBElement

         );
     public JAXBElement

          getTerm(); 

用XmlElementDecl注释的元素工厂方法用于创建一个包含XML元素名称的JAXBElement实例。 元素属性上存在@XmlElementRef注释，表示使用JAXBElement实例的元素名称，而不是从JavaBean属性名称派生XML元素名称。

用法受以下限制：

• 如果集合项目类型（用于集合属性）或属性类型（单值属性）为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中的“Package Specification”。

示例1：Ant任务示例

以下Java类层次结构模拟Ant构建脚本。 Ant任务对应于类层次结构中的类。 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> 

有一个类扩展Task没有XmlRootElement是不是一个错误。 但是，它们不能显示在XML实例中（因为它们没有XML元素名称）。

示例2：XML模式支持组支持

以下示例显示了XML模式替换组的注释。 注释和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

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	name
String	namespace 此参数和 name()用于确定JavaBean属性的XML元素。
boolean	required 自定义元素声明是必需的。
类	type 引用的Java类型。

Element Detail

type

public abstract 类 type

引用的Java类型。

如果该值为DEFAULT.class，则从JavaBean属性的类型推断该类型。

Default:

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元素名称是与类型静态关联的XML元素名称，使用类型上的注释XmlRootElement 。 如果类型没有注释与XmlElementDecl ，那么这是一个错误。

如果type()不是JAXBElement.class ，则该值必须为“”。

Default:

“”

name

public abstract String name

另请参见：

namespace()

Default:

“＃＃默认”

required

public abstract boolean required

自定义元素声明是必需的。

如果required（）为true，则Javabean属性将映射到具有minOccurs =“1”的XML模式元素声明。 maxOccurs对于单值属性为“1”，对于多值属性为“无界”。

如果required（）为false，则Javabean属性将映射到具有minOccurs =“0”的XML Schema元素声明。 maxOccurs对于单值属性为“1”，对于多值属性为“无界”。

为了兼容JAXB 2.1，此属性默认为true ，尽管XmlElement.required()默认为false。

从以下版本开始：

2.2

Default:

真正