XmlAnyElement (Java EE 5)

@Retention(value=RUNTIME)
@Target(value={FIELD, METHOD})

将 JavaBean 属性映射到 XML 信息集表示形式和/或 JAXB 元素。

在将 xml 内容解组到 JAXB 注释类的实例中时，此注释充当 "catch-all" 属性。它通常注释多值的 JavaBean 属性，但它也能够出现在单值的 JavaBean 属性中。在解组过程中，与类中用于其他 JavaBean 属性的静态 @XmlElement 或 @XmlElementRef 注释不匹配的每个 xml 元素都将被添加到此 "catch-all" 属性中。

用法：

 @XmlAnyElement
 public Element[] others;
 
 // Collection of Element or JAXB elements.
 @XmlAnyElement(lax="true")
 public Object[] others;

 @XmlAnyElement
 private List<Element> nodes;

 @XmlAnyElement
 private Element node;
 

限制用法约束

此注释与 XmlElement、XmlAttribute、XmlValue、XmlElements、XmlID 和 XmlIDREF 互斥。

在类及其超类中只能有一个 XmlAnyElement 注释的 JavaBean 属性。

与其他注释的关系

此注释可与 XmlJavaTypeAdapter 一起使用，以便用户能够将他们自己的数据结构映射到 DOM，然后可将这些 DOM 组成 XML。

此注释可以按如下方式与 XmlMixed 一起使用：

 // List of java.lang.String or DOM nodes.
 @XmlAnyElement @XmlMixed
 List<Object> others;
 

将模式转换为 Java 类的示例

以下模式将生成以下 Java 类：

 <xs:complextype name="foo">
   <xs:sequence>
     <xs:element name="a" type="xs:int">
     </xs:element><xs:element name="b" type="xs:int">
     <xs:any namespace="##other" processcontents="lax" minoccurs="0" maxoccurs="unbounded">
   </xs:any></xs:element></xs:sequence>
 </xs:complextype>
 

 class Foo {
   int a;
   int b;
   @XmlAnyElement
   List<Element> any;
 }
 

它可以按如下方式解组实例：

 <foo xmlns:e="extra">
   <a>1</a>
<e:other>  // this will be bound to DOM, because unmarshalling is orderless
   <b>3</b>
   </e:other><e:other>
<c>5</c>     // this will be bound to DOM, because the annotation doesn't remember namespaces.
 </e:other></foo>
 

以下模式将生成以下 Java 类：

 <xs:complextype name="bar">
   <xs:complexcontent>
   <xs:extension base="foo">
     <xs:sequence>
       <xs:element name="c" type="xs:int">
       <xs:any namespace="##other" processcontents="lax" minoccurs="0" maxoccurs="unbounded">
     </xs:any></xs:element></xs:sequence>
   </xs:extension>
 </xs:complexcontent></xs:complextype>
 

class Bar extends Foo {
int c;
// Foo.getAny() also represents wildcard content for type definition bar.
 }
 

它可以按如下方式解组实例：

 <bar xmlns:e="extra">
   <a>1</a>
<e:other>  // this will be bound to DOM, because unmarshalling is orderless
   <b>3</b>
   </e:other><e:other>
<c>5</c>     // this now goes to Bar.c
</e:other><e:other>  // this will go to Foo.any
 </e:other></bar>
 

将 XmlElementRef 与 XmlAnyElement 一起使用

XmlAnyElement 注释可与 XmlElementRef 一起使用，用于指派能够参与目录树的其他元素。

以下模式将生成以下 Java 类：

 <xs:complextype name="foo">
   <xs:choice maxoccurs="unbounded" minoccurs="0">
     <xs:element name="a" type="xs:int">
     </xs:element><xs:element name="b" type="xs:int">
     <xs:any namespace="##other" processcontents="lax">
   </xs:any></xs:element></xs:choice>
 </xs:complextype>
 

 class Foo {
   @XmlAnyElement(lax="true")
   @XmlElementRefs({
     @XmlElementRef(name="a", type="JAXBElement.class")
     @XmlElementRef(name="b", type="JAXBElement.class")
   })
   List<Object> others;
 }

 @XmlRegistry
 class ObjectFactory {
   ...
   @XmlElementDecl(name = "a", namespace = "", scope = Foo.class)
   JAXBElement<Integer> createFooA( Integer i ) { ... }

   @XmlElementDecl(name = "b", namespace = "", scope = Foo.class)
   JAXBElement<Integer> createFooB( Integer i ) { ... }
 

它可以按如下方式解组实例：

 <foo xmlns:e="extra">
<a>1</a>     // this will unmarshal to a <a href="../javax.xml.bind.JAXBElement.html"><code>JAXBElement</code></a> instance whose value is 1.
<e:other>  // this will unmarshal to a DOM <a href="../org.w3c.dom.Element.html"><code>Element</code></a>.
<b>3</b>     // this will unmarshal to a <a href="../javax.xml.bind.JAXBElement.html"><code>JAXBElement</code></a> instance whose value is 1.
 </e:other></foo>
 

W3C XML 模式 "lax" 通配符仿真

注释的 lax 元素启用了 "lax" 通配符语义的仿真。例如，当按如下方式注释 Java 源代码时：

 @XmlRootElement
 class Foo {
   @XmlAnyElement(lax=true)
   public Object[] others;
 }
 

那么下列文档将按如下方式解组：

 <foo>
   <unknown>
   </unknown></foo><foo>
 </foo>

Foo foo = unmarshal();
// 1 for 'unknown', another for 'foo'
assert foo.others.length==2;
// 'unknown' unmarshals to a DOM element
assert foo.others[0] instanceof Element;
// because of lax=true, the 'foo' element eagerly
// unmarshals to a Foo object.
assert foo.others[1] instanceof Foo;
 

since

JAXB2.0

英文文档：

Maps a JavaBean property to XML infoset representation and/or JAXB element.

This annotation serves as a "catch-all" property while unmarshalling xml content into a instance of a JAXB annotated class. It typically annotates a multi-valued JavaBean property, but it can occur on single value JavaBean property. During unmarshalling, each xml element that does not match a static @XmlElement or @XmlElementRef annotation for the other JavaBean properties on the class, is added to this "catch-all" property.

Usages:

 @XmlAnyElement
 public Element[] others;
 
 // Collection of Element or JAXB elements.
 @XmlAnyElement(lax="true")
 public Object[] others;

 @XmlAnyElement
 private List<Element> nodes;

 @XmlAnyElement
 private Element node;
 

Restriction usage constraints

This annotation is mutually exclusive with XmlElement, XmlAttribute, XmlValue, XmlElements, XmlID, and XmlIDREF.

There can be only one XmlAnyElement annotated JavaBean property in a class and its super classes.

Relationship to other annotations

This annotation can be used with XmlJavaTypeAdapter, so that users can map their own data structure to DOM, which in turn can be composed into XML.

This annotation can be used with XmlMixed like this:

 // List of java.lang.String or DOM nodes.
 @XmlAnyElement @XmlMixed
 List<Object> others;
 

Schema To Java example

The following schema would produce the following Java class:

 <xs:complextype name="foo">
   <xs:sequence>
     <xs:element name="a" type="xs:int">
     </xs:element><xs:element name="b" type="xs:int">
     <xs:any namespace="##other" processcontents="lax" minoccurs="0" maxoccurs="unbounded">
   </xs:any></xs:element></xs:sequence>
 </xs:complextype>
 

 class Foo {
   int a;
   int b;
   @XmlAnyElement
   List<Element> any;
 }
 

It can unmarshal instances like

 <foo xmlns:e="extra">
   <a>1</a>
   <e:other>  // this will be bound to DOM, because unmarshalling is orderless
   <b>3</b>
   </e:other><e:other>
   <c>5</c>     // this will be bound to DOM, because the annotation doesn't remember namespaces.
 </e:other></foo>
 

The following schema would produce the following Java class:

 <xs:complextype name="bar">
   <xs:complexcontent>
   <xs:extension base="foo">
     <xs:sequence>
       <xs:element name="c" type="xs:int">
       <xs:any namespace="##other" processcontents="lax" minoccurs="0" maxoccurs="unbounded">
     </xs:any></xs:element></xs:sequence>
   </xs:extension>
 </xs:complexcontent></xs:complextype>
 

 class Bar extends Foo {
   int c;
   // Foo.getAny() also represents wildcard content for type definition bar.
 }
 

It can unmarshal instances like

 <bar xmlns:e="extra">
   <a>1</a>
   <e:other>  // this will be bound to DOM, because unmarshalling is orderless
   <b>3</b>
   </e:other><e:other>
   <c>5</c>     // this now goes to Bar.c
   </e:other><e:other>  // this will go to Foo.any
 </e:other></bar>
 

Using XmlAnyElement with XmlElementRef

The XmlAnyElement annotation can be used with XmlElementRefs to designate additional elements that can participate in the content tree.

The following schema would produce the following Java class:

 <xs:complextype name="foo">
   <xs:choice maxoccurs="unbounded" minoccurs="0">
     <xs:element name="a" type="xs:int">
     </xs:element><xs:element name="b" type="xs:int">
     <xs:any namespace="##other" processcontents="lax">
   </xs:any></xs:element></xs:choice>
 </xs:complextype>
 

 class Foo {
   @XmlAnyElement(lax="true")
   @XmlElementRefs({
     @XmlElementRef(name="a", type="JAXBElement.class")
     @XmlElementRef(name="b", type="JAXBElement.class")
   })
   List<Object> others;
 }

 @XmlRegistry
 class ObjectFactory {
   ...
   @XmlElementDecl(name = "a", namespace = "", scope = Foo.class)
   JAXBElement<Integer> createFooA( Integer i ) { ... }

   @XmlElementDecl(name = "b", namespace = "", scope = Foo.class)
   JAXBElement<Integer> createFooB( Integer i ) { ... }
 

It can unmarshal instances like

 <foo xmlns:e="extra">
   <a>1</a>     // this will unmarshal to a <a href="../../../../javax/xml/bind/JAXBElement.html" title="class in javax.xml.bind"><code>JAXBElement</code></a> instance whose value is 1.
   <e:other>  // this will unmarshal to a DOM <a href="http://java.sun.com/j2se/1.5/docs/api/org/w3c/dom/Element.html" title="class or interface in org.w3c.dom"><code>Element</code></a>.
   <b>3</b>     // this will unmarshal to a <a href="../../../../javax/xml/bind/JAXBElement.html" title="class in javax.xml.bind"><code>JAXBElement</code></a> instance whose value is 1.
 </e:other></foo>
 

W3C XML Schema "lax" wildcard emulation

The lax element of the annotation enables the emulation of the "lax" wildcard semantics. For example, when the Java source code is annotated like this:

 @XmlRootElement
 class Foo {
   @XmlAnyElement(lax=true)
   public Object[] others;
 }
 

then the following document will unmarshal like this:

 <foo>
   <unknown>
   </unknown></foo><foo>
 </foo>

 Foo foo = unmarshal();
 // 1 for 'unknown', another for 'foo'
 assert foo.others.length==2;
 // 'unknown' unmarshals to a DOM element
 assert foo.others[0] instanceof Element;
 // because of lax=true, the 'foo' element eagerly
 // unmarshals to a Foo object.
 assert foo.others[1] instanceof Foo;
 

Since:

JAXB2.0

Author:

Kohsuke Kawaguchi

---

Optional Element Summary
boolean	lax           Controls the unmarshaller behavior when it sees elements known to the current JAXBContext.
Class<? extends DomHandler>	value           Specifies the DomHandler which is responsible for actually converting XML from/to a DOM-like data structure.

 

abstract public boolean lax()
在查看当前 JAXBContext 中的已知元素时控制解组行为。

当为 false 时

如果为 false，则所有与该属性匹配的元素都将被解组为 DOM，并且该属性将只包含 DOM 元素。

当为 true 时

如果为 true，则当某一元素与使用 JAXBContext 已知的 XmlAnyElement 标记的属性匹配时（例如，存在具有相同标记名称的带有 XmlRootElement 的类，或者存在具有相同标记名称的 XmlElementDecl），unmarshaller 会立即将此元素解组到 JAXB 对象，而不是解组到 DOM。此外，如果元素是未知的，但它有一个已知的 xsi:type，则通过使用未知的元素名称和设置为已知 xsi:type 的 JAXB 映射实例的 JAXBElement 值，unmarshaller 可立即将此元素解组到 JAXBElement。

因此，在解组之后，属性可能变得完全不同，它可能在包含 DOM 节点的同时还包含一些 JAXB 对象。

可以使用这种特性来仿真 W3C XML 模式的 "lax" 通配符语义。

英文文档：

lax

public abstract boolean lax

Controls the unmarshaller behavior when it sees elements known to the current JAXBContext.

When false

If false, all the elements that match the property will be unmarshalled to DOM, and the property will only contain DOM elements.

When true

If true, when an element matches a property marked with XmlAnyElement is known to JAXBContext (for example, there's a class with XmlRootElement that has the same tag name, or there's XmlElementDecl that has the same tag name), the unmarshaller will eagerly unmarshal this element to the JAXB object, instead of unmarshalling it to DOM. Additionally, if the element is unknown but it has a known xsi:type, the unmarshaller eagerly unmarshals the element to a JAXBElement, with the unknown element name and the JAXBElement value is set to an instance of the JAXB mapping of the known xsi:type.

As a result, after the unmarshalling, the property can become heterogeneous; it can have both DOM nodes and some JAXB objects at the same time.

This can be used to emulate the "lax" wildcard semantics of the W3C XML Schema.

Default:

false

---

abstract public Class<T> value()
指定 DomHandler，它负责实际执行 XML 与类 DOM 数据结构之间的转换。

英文文档：

value

public abstract Class<? extends DomHandler> value

Specifies the DomHandler which is responsible for actually converting XML from/to a DOM-like data structure.

Default:

javax.xml.bind.annotation.W3CDomHandler.class

---

Overview  Package   Class  Tree  Deprecated  Index  Help
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: REQUIRED | OPTIONAL	DETAIL: ELEMENT

---

Submit a bug or feature

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.