/*
* Copyright 2005 Sun Microsystems, Inc. All rights reserved.
* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*/
package javax.xml.bind.annotation;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import java.util.List;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBElement;
import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
import org.w3c.dom.Element;
/**
* Maps a JavaBean property to XML infoset representation and/or JAXB element.
*
* <p>
* 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.
*
* <p>
* <h2>Usages:</h2>
*
* <pre>
* @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;
* </pre>
*
* <h2>Restriction usage constraints</h2>
* <p>
* This annotation is mutually exclusive with {@link XmlElement},
* {@link XmlAttribute}, {@link XmlValue}, {@link XmlElements}, {@link XmlID},
* and {@link XmlIDREF}.
*
* <p>
* There can be only one {@link XmlAnyElement} annotated JavaBean property in a
* class and its super classes.
*
* <h2>Relationship to other annotations</h2>
* <p>
* 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.
*
* <p>
* This annotation can be used with {@link XmlMixed} like this:
*
* <pre>
* // List of java.lang.String or DOM nodes.
* @XmlAnyElement
* @XmlMixed
* List<Object> others;
* </pre>
*
*
* <h2>Schema To Java example</h2>
*
* The following schema would produce the following Java class:
*
* <pre>
* <xmp>
* <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>
* </xmp>
* </pre>
*
* <pre>
* class Foo {
* int a;
* int b;
* @{@link XmlAnyElement}
* List<Element> any;
* }
* </pre>
*
* It can unmarshal instances like
*
* <pre>
* <xmp>
* <foo xmlns:e="extra">
* <a>1</a>
* <e:other /> // this will be bound to DOM, because unmarshalling is orderless
* <b>3</b>
* <e:other />
* <c>5</c> // this will be bound to DOM, because the annotation doesn't remember namespaces.
* </foo>
* </xmp>
* </pre>
*
*
*
* The following schema would produce the following Java class:
*
* <pre>
* <xmp>
* <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>
* </xmp>
* </pre>
*
* <pre>
* <xmp>
* class Bar extends Foo {
* int c;
* // Foo.getAny() also represents wildcard content for type definition bar.
* }
* </xmp>
* </pre>
*
*
* It can unmarshal instances like
*
* <pre>
* <xmp>
* <bar xmlns:e="extra">
* <a>1</a>
* <e:other /> // this will be bound to DOM, because unmarshalling is orderless
* <b>3</b>
* <e:other />
* <c>5</c> // this now goes to Bar.c
* <e:other /> // this will go to Foo.any
* </bar>
* </xmp>
* </pre>
*
*
*
*
* <h2>Using {@link XmlAnyElement} with {@link XmlElementRef}</h2>
* <p>
* The {@link XmlAnyElement} annotation can be used with {@link XmlElementRef}s
* to designate additional elements that can participate in the content tree.
*
* <p>
* The following schema would produce the following Java class:
*
* <pre>
* <xmp>
* <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>
* </xmp>
* </pre>
*
* <pre>
* 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 ) { ... }
* </pre>
*
* It can unmarshal instances like
*
* <pre>
* <xmp>
* <foo xmlns:e="extra">
* <a>1</a> // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
* <e:other /> // this will unmarshal to a DOM {@link Element}.
* <b>3</b> // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
* </foo>
* </xmp>
* </pre>
*
*
*
*
* <h2>W3C XML Schema "lax" wildcard emulation</h2>
* 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:
*
* <pre>
* @{@link XmlRootElement}
* class Foo {
* @XmlAnyElement(lax=true)
* public {@link Object}[] others;
* }
* </pre>
*
* then the following document will unmarshal like this:
*
* <pre>
* <xmp>
* <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;
* </xmp>
* </pre>
*
*
* @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}.
*
* <h3>When false</h3>
* <p>
* If false, all the elements that match the property will be unmarshalled
* to DOM, and the property will only contain DOM elements.
*
* <h3>When true</h3>
* <p>
* 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.
*
* <p>
* 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.
*
* <p>
* 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<? extends DomHandler> value() default W3CDomHandler.class;
}
|