XmlElementRef (Java Platform SE 8 )

@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:
    
    真正

Annotation Type XmlElementRef

支持XML Schema替换组

Optional Element Summary

Element Detail

type

namespace

name

required