* 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. * *
*
* @XmlAnyElement
* public {@link Element}[] others;
*
* // Collection of {@link Element} or JAXB elements.
* @XmlAnyElement(lax="true")
* public {@link Object}[] others;
*
* @XmlAnyElement
* private List<{@link Element}> nodes;
*
* @XmlAnyElement
* private {@link Element} node;
*
*
* * This annotation is mutually exclusive with * {@link XmlElement}, {@link XmlAttribute}, {@link XmlValue}, * {@link XmlElements}, {@link XmlID}, and {@link XmlIDREF}. * *
* There can be only one {@link XmlAnyElement} annotated JavaBean property * in a class and its super classes. * *
* This annotation can be used with {@link 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 {@link XmlMixed} like this: *
* // List of java.lang.String or DOM nodes. * @XmlAnyElement @XmlMixed * List<Object> others; ** * *
* <xs:complexType name="foo"> * <xs:sequence> * <xs:element name="a" type="xs:int" /> * <xs:element name="b" type="xs:int" /> * <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" /> * </xs:sequence> * </xs:complexType> ** *
* class Foo {
* int a;
* int b;
* @{@link XmlAnyElement}
* List<Element> any;
* }
*
*
* It can unmarshal instances like
*
* * <foo xmlns:e="extra"> * <a>1 * <e:other /> // this will be bound to DOM, because unmarshalling is orderless * <b>3 * <e:other /> * <c>5 // this will be bound to DOM, because the annotation doesn't remember namespaces. * </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:sequence> * </xs:extension> * </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 * <e:other /> // this will be bound to DOM, because unmarshalling is orderless * <b>3 * <e:other /> * <c>5 // this now goes to Bar.c * <e:other /> // this will go to Foo.any * </bar> ** * * * *
* The {@link XmlAnyElement} annotation can be used with {@link XmlElementRef}s 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 name="b" type="xs:int" /> * <xs:any namespace="##other" processContents="lax" /> * </xs:choice> * </xs:complexType> ** *
* class Foo {
* @{@link XmlAnyElement}(lax="true")
* @{@link XmlElementRefs}({
* @{@link XmlElementRef}(name="a", type="JAXBElement.class")
* @{@link XmlElementRef}(name="b", type="JAXBElement.class")
* })
* {@link List}<{@link Object}> others;
* }
*
* @XmlRegistry
* class ObjectFactory {
* ...
* @XmlElementDecl(name = "a", namespace = "", scope = Foo.class)
* {@link JAXBElement}<Integer> createFooA( Integer i ) { ... }
*
* @XmlElementDecl(name = "b", namespace = "", scope = Foo.class)
* {@link JAXBElement}<Integer> createFooB( Integer i ) { ... }
*
*
* It can unmarshal instances like
*
*
* <foo xmlns:e="extra">
* <a>1 // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
* <e:other /> // this will unmarshal to a DOM {@link Element}.
* <b>3 // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
* </foo>
*
*
*
*
*
*
* @{@link XmlRootElement}
* class Foo {
* @XmlAnyElement(lax=true)
* public {@link Object}[] others;
* }
*
* then the following document will unmarshal like this:
* * <foo> * <unknown /> * <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; ** * @author Kohsuke Kawaguchi * @since JAXB2.0 */ @Retention(RUNTIME) @Target({FIELD,METHOD}) public @interface XmlAnyElement { /** * Controls the unmarshaller behavior when it sees elements * known to the current {@link JAXBContext}. * *
* If false, all the elements that match the property will be unmarshalled * to DOM, and the property will only contain DOM elements. * *
* If true, when an element matches a property marked with {@link XmlAnyElement} * is known to {@link JAXBContext} (for example, there's a class with * {@link XmlRootElement} that has the same tag name, or there's * {@link 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 {@link 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. */ boolean lax() default false; /** * Specifies the {@link DomHandler} which is responsible for actually * converting XML from/to a DOM-like data structure. */ Class value() default W3CDomHandler.class; }