uTools-Manuals/docs/java/javax/xml/bind/annotation/XmlElementRef.html

<div class="header">
<div class="subTitle">
     javax.xml.bind.annotation 
   </div>
<h2 class="title" title="Annotation Type XmlElementRef">Annotation Type XmlElementRef</h2>
</div><div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr/> <br/> <pre><a href="../../../../java/lang/annotation/Retention.html" title="annotation in java.lang.annotation">@Retention</a>(<a href="../../../../java/lang/annotation/Retention.html#value--">value</a>=<a href="../../../../java/lang/annotation/RetentionPolicy.html#RUNTIME">RUNTIME</a>)
 <a href="../../../../java/lang/annotation/Target.html" title="annotation in java.lang.annotation">@Target</a>(<a href="../../../../java/lang/annotation/Target.html#value--">value</a>={<a href="../../../../java/lang/annotation/ElementType.html#FIELD">字段</a>,<a href="../../../../java/lang/annotation/ElementType.html#METHOD">METHOD</a>})
public @interface <span class="memberNameLabel">XmlElementRef</span></pre>
<div class="block">
<p> <span>将JavaBean属性映射到从属性类型派生的XML元素。</span> </p>
<p> <span><b>用法</b></span> </p>
<p> <span><tt>@XmlElementRef</tt>注释可以使用JavaBean属性或从<a href="../../../../javax/xml/bind/annotation/XmlElementRefs.html" title="javax.xml.bind.annotation中的注释"><code>XmlElementRefs</code></a></span> </p>
<p> <span>此注释将XML元素名称与JavaBean属性动态关联。</span> <span>当JavaBean属性用<a href="../../../../javax/xml/bind/annotation/XmlElement.html" title="javax.xml.bind.annotation中的注释"><code>XmlElement</code>注释</a>时，XML元素名称是从JavaBean属性名称静态派生的。</span> <span>但是，当使用此注释时，XML元素名称将在运行时从JavaBean属性类型的实例派生。</span> </p>
<h3> <span>支持XML Schema替换组</span> </h3>
<span>XML Schema允许XML文档作者使用未使用替换组在模式的内容模型中静态指定的XML元素名称。</span>
<span>Schema派生代码使用<i>元素属性</i> （第5.5.5节“JAXB 2.0规范的”元素属性“）支持替换组。</span>
<span>元素属性方法签名的格式如下：</span>
<pre>  <span>public void setTerm(JAXBElement

         <!--? extends Operator-->);
     public JAXBElement

         <!--? extends Operator--> getTerm();</span> </pre>
<p> <span>用<a href="../../../../javax/xml/bind/annotation/XmlElementDecl.html" title="javax.xml.bind.annotation中的注释"><code>XmlElementDecl</code>注释</a>的元素工厂方法用于创建一个包含XML元素名称的<tt>JAXBElement</tt>实例。</span> <span>元素属性上存在@XmlElementRef注释，表示使用<tt>JAXBElement</tt>实例的元素名称，而不是从JavaBean属性名称派生XML元素名称。</span> </p>
<p> <span>用法受以下限制：</span> </p>
<ul>
<li> <span>如果集合项目类型（用于集合属性）或属性类型（单值属性）为<a href="../../../../javax/xml/bind/JAXBElement.html" title="javax.xml.bind中的类"><code>JAXBElement</code></a> ，则<tt>@XmlElementRef}.name()</tt>和<tt>@XmlElementRef.namespace()</tt>必须使用@XmlRegistry（通常由ObjectFactory类生成的类）指向带有@XmlElementDecl注释的元素工厂方法模式编译器）：</span>
<ul>
<li> <span>@ XmlElementDecl.name（）必须等于@ XmlElementRef.name（）</span> </li>
<li> <span>@ XmlElementDecl.namespace（）必须等于@ XmlElementRef.namespace（）。</span> </li>
</ul></li>
<li> <span>如果集合项目类型（对于集合属性）或属性类型（对于单值属性）不是<a href="../../../../javax/xml/bind/JAXBElement.html" title="javax.xml.bind中的类"><code>JAXBElement</code></a> ，则属性或字段引用的类型必须使用<code>XmlRootElement</code> <a href="../../../../javax/xml/bind/annotation/XmlRootElement.html" title="javax.xml.bind.annotation中的注释">注释</a> 。</span> </li>
<li> <span>此注释可与以下注释一起使用： <a href="../../../../javax/xml/bind/annotation/XmlElementWrapper.html" title="javax.xml.bind.annotation中的注释"><code>XmlElementWrapper</code></a> ， <a href="../../../../javax/xml/bind/annotation/adapters/XmlJavaTypeAdapter.html" title="javax.xml.bind.annotation.adapters中的注释"><code>XmlJavaTypeAdapter</code></a> 。</span> </li>
</ul>
<p> <span>有关其他常见信息，请参阅javax.xml.bind.package javadoc中的“Package Specification”。</span> </p>
<p> <span><b>示例1：Ant任务示例</b></span> </p>
<span>以下Java类层次结构模拟Ant构建脚本。</span>
<span>Ant任务对应于类层次结构中的类。</span>
<span>Ant任务的XML元素名称由其相应类上的@XmlRootElement注释指示。</span>
<pre>  <span>@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&lt;Task&gt; tasks;
     }

     abstract class Task {
     }

     @XmlRootElement(name="jar")
     class JarTask extends Task {
         ...
     }

     @XmlRootElement(name="javac")
     class JavacTask extends Task {
         ...
     }

     &lt;!-- XML Schema fragment --&gt;
     &lt;xs:element name="target" type="Target"&gt;
     &lt;xs:complexType name="Target"&gt;
       &lt;xs:sequence&gt;
         &lt;xs:choice maxOccurs="unbounded"&gt;
           &lt;xs:element ref="jar"&gt;
           &lt;xs:element ref="javac"&gt;
         &lt;/xs:choice&gt;
       &lt;/xs:sequence&gt;
     &lt;/xs:complexType&gt;</span> </pre>
<p> <span>因此下面的代码片段：</span> </p>
<pre>  <span>Target target = new Target();
     target.tasks.add(new JarTask());
     target.tasks.add(new JavacTask());
     marshal(target);</span> </pre>
<span>将产生以下XML输出：</span>
<pre>  <span>&lt;target&gt;
       &lt;jar&gt;
         ....
       &lt;/jar&gt;
       &lt;javac&gt;
         ....
       &lt;/javac&gt;
     &lt;/target&gt;</span> </pre>
<p> <span>有一个类扩展<tt>Task</tt>没有<a href="../../../../javax/xml/bind/annotation/XmlRootElement.html" title="javax.xml.bind.annotation中的注释"><code>XmlRootElement</code></a>是不是一个错误。</span> <span>但是，它们不能显示在XML实例中（因为它们没有XML元素名称）。</span> </p>
<p> <span><b>示例2：XML模式支持组支持</b></span> </p>
<p> <span>以下示例显示了XML模式替换组的注释。</span> <span>注释和ObjectFactory是从模式派生的。</span> </p>
<pre>  <span>@XmlElement
     class Math {
         //  The value of <a href="../../../../javax/xml/bind/annotation/XmlElementRef.html#type--"><code>type()</code></a>is
         //  JAXBElement.class , which indicates the XML
         //  element name ObjectFactory - in general a class marked
         //  with @XmlRegistry. (See ObjectFactory below)
         //
         //  The <a href="../../../../javax/xml/bind/annotation/XmlElementRef.html#name--"><code>name()</code></a> is "operator", a pointer to a
         // factory method annotated with a
         //  <a href="../../../../javax/xml/bind/annotation/XmlElementDecl.html" title="annotation in javax.xml.bind.annotation"><code>XmlElementDecl</code></a> 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&lt;? extends Operator&gt; term;
     }

     @XmlRegistry
     class ObjectFactory {
         @XmlElementDecl(name="operator")
         JAXBElement&lt;Operator&gt; createOperator(Operator o) {...}
         @XmlElementDecl(name="add",substitutionHeadName="operator")
         JAXBElement&lt;Operator&gt; createAdd(Operator o) {...}
         @XmlElementDecl(name="sub",substitutionHeadName="operator")
         JAXBElement&lt;Operator&gt; createSub(Operator o) {...}
     }

     class Operator {
         ...
     }</span> </pre>
<p> <span>因此，以下代码片段</span> </p>
<pre>  <span>Math m = new Math();
     m.term = new ObjectFactory().createAdd(new Operator());
     marshal(m);</span> </pre>
<span>将产生以下XML输出：</span>
<pre>  <span>&lt;math&gt;
       &lt;add&gt;...&lt;/add&gt;
     &lt;/math&gt;</span> </pre>
</div>
<dl>
<dt>
<span class="simpleTagLabel">从以下版本开始：</span>
</dt>
<dd>
         JAXB2.0 
       </dd>
<dt>
<span class="seeLabel">另请参见：</span>
</dt>
<dd>
<span><a href="../../../../javax/xml/bind/annotation/XmlElementRefs.html" title="javax.xml.bind.annotation中的注释"><code>XmlElementRefs</code></a></span>
</dd>
</dl> </li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- =========== ANNOTATION TYPE OPTIONAL MEMBER SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.optional.element.summary">
<!-- --> </a> <h3>Optional Element Summary</h3>
<table border="0" cellpadding="3" cellspacing="0" class="memberSummary" summary="Optional Element Summary table, listing optional elements, and an explanation">
<caption>
<span>Optional Elements</span>
<span class="tabEnd"> </span>
</caption>
<tbody>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Optional Element and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code><a href="../../../../java/lang/String.html" title="class in java.lang">String</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../javax/xml/bind/annotation/XmlElementRef.html#name--">name</a></span></code> </td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code><a href="../../../../java/lang/String.html" title="class in java.lang">String</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../javax/xml/bind/annotation/XmlElementRef.html#namespace--">namespace</a></span></code>
<div class="block">
              此参数和 
             <a href="../../../../javax/xml/bind/annotation/XmlElementRef.html#name--"><code>name()</code></a>用于确定JavaBean属性的XML元素。 
            </div> </td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../javax/xml/bind/annotation/XmlElementRef.html#required--">required</a></span></code>
<div class="block">
              自定义元素声明是必需的。 
            </div> </td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code><a href="../../../../java/lang/Class.html" title="class in java.lang">类</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../javax/xml/bind/annotation/XmlElementRef.html#type--">type</a></span></code>
<div class="block">
              引用的Java类型。 
            </div> </td>
</tr>
</tbody>
</table> </li>
</ul> </li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.element.detail">
<!-- --> </a> <h3>Element Detail</h3> <a name="type--">
<!-- --> </a>
<ul class="blockList">
<li class="blockList"> <h4>type</h4> <pre>public abstract <a href="../../../../java/lang/Class.html" title="class in java.lang">类</a> type</pre>
<div class="block">
<span>引用的Java类型。</span>
<p> <span>如果该值为DEFAULT.class，则从JavaBean属性的类型推断该类型。</span> </p>
</div>
<dl>
<dt>
             Default: 
           </dt>
<dd>
             javax.xml.bind.annotation.XmlElementRef.DEFAULT.class 
           </dd>
</dl> </li>
</ul> </li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="namespace--">
<!-- --> </a>
<ul class="blockList">
<li class="blockList"> <h4>namespace</h4> <pre>public abstract <a href="../../../../java/lang/String.html" title="class in java.lang">String</a> namespace</pre>
<div class="block">
<span>此参数和<a href="../../../../javax/xml/bind/annotation/XmlElementRef.html#name--"><code>name()</code></a>用于确定JavaBean属性的XML元素。</span>
<p> <span>如果<tt>type()</tt>是<tt>JAXBElement.class</tt> ，那么<tt>namespace()</tt>和<tt>name()</tt>指向一个工厂方法与<a href="../../../../javax/xml/bind/annotation/XmlElementDecl.html" title="javax.xml.bind.annotation中的注释"><code>XmlElementDecl</code></a> 。</span> <span>XML元素名称是从工厂方法的<a href="../../../../javax/xml/bind/annotation/XmlElementDecl.html" title="javax.xml.bind.annotation中的注释"><code>XmlElementDecl</code></a>注释中的元素名称，或者如果在XML文档中替换了来自其替换组（其中是头元素）的元素，则元素名称来自<a href="../../../../javax/xml/bind/annotation/XmlElementDecl.html" title="javax.xml.bind.annotation中的注释">取代</a>的<code>XmlElementDecl</code>元件。</span> </p>
<p> <span>如果<a href="../../../../javax/xml/bind/annotation/XmlElementRef.html#type--"><code>type()</code></a>不是<tt>JAXBElement.class</tt> ，则XML元素名称是与类型静态关联的XML元素名称，使用类型上的注释<a href="../../../../javax/xml/bind/annotation/XmlRootElement.html" title="javax.xml.bind.annotation中的注释"><code>XmlRootElement</code></a> 。</span> <span>如果类型没有注释与<a href="../../../../javax/xml/bind/annotation/XmlElementDecl.html" title="javax.xml.bind.annotation中的注释"><code>XmlElementDecl</code></a> ，那么这是一个错误。</span> </p>
<p> <span>如果<tt>type()</tt>不是<tt>JAXBElement.class</tt> ，则该值必须为“”。</span> </p>
</div>
<dl>
<dt>
             Default: 
           </dt>
<dd>
             “” 
           </dd>
</dl> </li>
</ul> </li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="name--">
<!-- --> </a>
<ul class="blockList">
<li class="blockList"> <h4>name</h4> <pre>public abstract <a href="../../../../java/lang/String.html" title="class in java.lang">String</a> name</pre>
<dl>
<dt>
<span class="seeLabel">另请参见：</span>
</dt>
<dd>
<a href="../../../../javax/xml/bind/annotation/XmlElementRef.html#namespace--"><code>namespace()</code></a>
</dd>
</dl>
<dl>
<dt>
             Default: 
           </dt>
<dd>
             “＃＃默认” 
           </dd>
</dl> </li>
</ul> </li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="required--">
<!-- --> </a>
<ul class="blockListLast">
<li class="blockList"> <h4>required</h4> <pre>public abstract boolean required</pre>
<div class="block">
<span>自定义元素声明是必需的。</span>
<p> <span>如果required（）为true，则Javabean属性将映射到具有minOccurs =“1”的XML模式元素声明。</span> <span>maxOccurs对于单值属性为“1”，对于多值属性为“无界”。</span> </p>
<p> <span>如果required（）为false，则Javabean属性将映射到具有minOccurs =“0”的XML Schema元素声明。</span> <span>maxOccurs对于单值属性为“1”，对于多值属性为“无界”。</span> </p>
<p> <span>为了兼容JAXB 2.1，此属性默认为<tt>true</tt> ，尽管<a href="../../../../javax/xml/bind/annotation/XmlElement.html#required--"><code>XmlElement.required()</code></a>默认为false。</span> </p>
</div>
<dl>
<dt>
<span class="simpleTagLabel">从以下版本开始：</span>
</dt>
<dd>
             2.2 
           </dd>
</dl>
<dl>
<dt>
             Default: 
           </dt>
<dd>
             真正 
           </dd>
</dl> </li>
</ul> </li>
</ul> </li>
</ul>
</div>
</div>