ohair@286: * This annotation serves as a "catch-all" property while unmarshalling ohair@286: * xml content into a instance of a JAXB annotated class. It typically ohair@286: * annotates a multi-valued JavaBean property, but it can occur on ohair@286: * single value JavaBean property. During unmarshalling, each xml element ohair@286: * that does not match a static @XmlElement or @XmlElementRef ohair@286: * annotation for the other JavaBean properties on the class, is added to this ohair@286: * "catch-all" property. ohair@286: * ohair@286: *
ohair@286: *
ohair@286: * @XmlAnyElement
ohair@286: * public {@link Element}[] others;
ohair@286: *
ohair@286: * // Collection of {@link Element} or JAXB elements.
ohair@286: * @XmlAnyElement(lax="true")
ohair@286: * public {@link Object}[] others;
ohair@286: *
ohair@286: * @XmlAnyElement
ohair@286: * private List<{@link Element}> nodes;
ohair@286: *
ohair@286: * @XmlAnyElement
ohair@286: * private {@link Element} node;
ohair@286: *
ohair@286: *
ohair@286: * ohair@286: * This annotation is mutually exclusive with ohair@286: * {@link XmlElement}, {@link XmlAttribute}, {@link XmlValue}, ohair@286: * {@link XmlElements}, {@link XmlID}, and {@link XmlIDREF}. ohair@286: * ohair@286: *
ohair@286: * There can be only one {@link XmlAnyElement} annotated JavaBean property ohair@286: * in a class and its super classes. ohair@286: * ohair@286: *
ohair@286: * This annotation can be used with {@link XmlJavaTypeAdapter}, so that users ohair@286: * can map their own data structure to DOM, which in turn can be composed ohair@286: * into XML. ohair@286: * ohair@286: *
ohair@286: * This annotation can be used with {@link XmlMixed} like this: ohair@286: *
ohair@286: * // List of java.lang.String or DOM nodes. ohair@286: * @XmlAnyElement @XmlMixed ohair@286: * List<Object> others; ohair@286: *ohair@286: * ohair@286: * ohair@286: *
ohair@286: * <xs:complexType name="foo"> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="a" type="xs:int" /> ohair@286: * <xs:element name="b" type="xs:int" /> ohair@286: * <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" /> ohair@286: * </xs:sequence> ohair@286: * </xs:complexType> ohair@286: *ohair@286: * ohair@286: *
ohair@286: * class Foo {
ohair@286: * int a;
ohair@286: * int b;
ohair@286: * @{@link XmlAnyElement}
ohair@286: * List<Element> any;
ohair@286: * }
ohair@286: *
ohair@286: *
ohair@286: * It can unmarshal instances like
ohair@286: *
ohair@286: * ohair@286: * <foo xmlns:e="extra"> ohair@286: * <a>1 ohair@286: * <e:other /> // this will be bound to DOM, because unmarshalling is orderless ohair@286: * <b>3 ohair@286: * <e:other /> ohair@286: * <c>5 // this will be bound to DOM, because the annotation doesn't remember namespaces. ohair@286: * </foo> ohair@286: *ohair@286: * ohair@286: * ohair@286: * ohair@286: * The following schema would produce the following Java class: ohair@286: *
ohair@286: * <xs:complexType name="bar"> ohair@286: * <xs:complexContent> ohair@286: * <xs:extension base="foo"> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="c" type="xs:int" /> ohair@286: * <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" /> ohair@286: * </xs:sequence> ohair@286: * </xs:extension> ohair@286: * </xs:complexType> ohair@286: *ohair@286: * ohair@286: *
ohair@286: * class Bar extends Foo {
ohair@286: * int c;
ohair@286: * // Foo.getAny() also represents wildcard content for type definition bar.
ohair@286: * }
ohair@286: *
ohair@286: *
ohair@286: *
ohair@286: * It can unmarshal instances like
ohair@286: *
ohair@286: * ohair@286: * <bar xmlns:e="extra"> ohair@286: * <a>1 ohair@286: * <e:other /> // this will be bound to DOM, because unmarshalling is orderless ohair@286: * <b>3 ohair@286: * <e:other /> ohair@286: * <c>5 // this now goes to Bar.c ohair@286: * <e:other /> // this will go to Foo.any ohair@286: * </bar> ohair@286: *ohair@286: * ohair@286: * ohair@286: * ohair@286: * ohair@286: *
ohair@286: * The {@link XmlAnyElement} annotation can be used with {@link XmlElementRef}s to ohair@286: * designate additional elements that can participate in the content tree. ohair@286: * ohair@286: *
ohair@286: * The following schema would produce the following Java class: ohair@286: *
ohair@286: * <xs:complexType name="foo"> ohair@286: * <xs:choice maxOccurs="unbounded" minOccurs="0"> ohair@286: * <xs:element name="a" type="xs:int" /> ohair@286: * <xs:element name="b" type="xs:int" /> ohair@286: * <xs:any namespace="##other" processContents="lax" /> ohair@286: * </xs:choice> ohair@286: * </xs:complexType> ohair@286: *ohair@286: * ohair@286: *
ohair@286: * class Foo {
ohair@286: * @{@link XmlAnyElement}(lax="true")
ohair@286: * @{@link XmlElementRefs}({
ohair@286: * @{@link XmlElementRef}(name="a", type="JAXBElement.class")
ohair@286: * @{@link XmlElementRef}(name="b", type="JAXBElement.class")
ohair@286: * })
ohair@286: * {@link List}<{@link Object}> others;
ohair@286: * }
ohair@286: *
ohair@286: * @XmlRegistry
ohair@286: * class ObjectFactory {
ohair@286: * ...
ohair@286: * @XmlElementDecl(name = "a", namespace = "", scope = Foo.class)
ohair@286: * {@link JAXBElement}<Integer> createFooA( Integer i ) { ... }
ohair@286: *
ohair@286: * @XmlElementDecl(name = "b", namespace = "", scope = Foo.class)
ohair@286: * {@link JAXBElement}<Integer> createFooB( Integer i ) { ... }
ohair@286: *
ohair@286: *
ohair@286: * It can unmarshal instances like
ohair@286: *
ohair@286: *
ohair@286: * <foo xmlns:e="extra">
ohair@286: * <a>1 // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
ohair@286: * <e:other /> // this will unmarshal to a DOM {@link Element}.
ohair@286: * <b>3 // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
ohair@286: * </foo>
ohair@286: *
ohair@286: *
ohair@286: *
ohair@286: *
ohair@286: *
ohair@286: *
ohair@286: * @{@link XmlRootElement}
ohair@286: * class Foo {
ohair@286: * @XmlAnyElement(lax=true)
ohair@286: * public {@link Object}[] others;
ohair@286: * }
ohair@286: *
ohair@286: * then the following document will unmarshal like this:
ohair@286: * ohair@286: * <foo> ohair@286: * <unknown /> ohair@286: * <foo /> ohair@286: * </foo> ohair@286: * ohair@286: * Foo foo = unmarshal(); ohair@286: * // 1 for 'unknown', another for 'foo' ohair@286: * assert foo.others.length==2; ohair@286: * // 'unknown' unmarshals to a DOM element ohair@286: * assert foo.others[0] instanceof Element; ohair@286: * // because of lax=true, the 'foo' element eagerly ohair@286: * // unmarshals to a Foo object. ohair@286: * assert foo.others[1] instanceof Foo; ohair@286: *ohair@286: * ohair@286: * @author Kohsuke Kawaguchi ohair@286: * @since JAXB2.0 ohair@286: */ ohair@286: @Retention(RUNTIME) ohair@286: @Target({FIELD,METHOD}) ohair@286: public @interface XmlAnyElement { ohair@286: ohair@286: /** ohair@286: * Controls the unmarshaller behavior when it sees elements ohair@286: * known to the current {@link JAXBContext}. ohair@286: * ohair@286: *
ohair@286: * If false, all the elements that match the property will be unmarshalled ohair@286: * to DOM, and the property will only contain DOM elements. ohair@286: * ohair@286: *
ohair@286: * If true, when an element matches a property marked with {@link XmlAnyElement} ohair@286: * is known to {@link JAXBContext} (for example, there's a class with ohair@286: * {@link XmlRootElement} that has the same tag name, or there's ohair@286: * {@link XmlElementDecl} that has the same tag name), ohair@286: * the unmarshaller will eagerly unmarshal this element to the JAXB object, ohair@286: * instead of unmarshalling it to DOM. Additionally, if the element is ohair@286: * unknown but it has a known xsi:type, the unmarshaller eagerly unmarshals ohair@286: * the element to a {@link JAXBElement}, with the unknown element name and ohair@286: * the JAXBElement value is set to an instance of the JAXB mapping of the ohair@286: * known xsi:type. ohair@286: * ohair@286: *
ohair@286: * As a result, after the unmarshalling, the property can become heterogeneous; ohair@286: * it can have both DOM nodes and some JAXB objects at the same time. ohair@286: * ohair@286: *
ohair@286: * This can be used to emulate the "lax" wildcard semantics of the W3C XML Schema. ohair@286: */ ohair@286: boolean lax() default false; ohair@286: ohair@286: /** ohair@286: * Specifies the {@link DomHandler} which is responsible for actually ohair@286: * converting XML from/to a DOM-like data structure. ohair@286: */ ohair@286: Class value() default W3CDomHandler.class; ohair@286: }