jakarta.xml.bind.annotation.XmlAnyElement Maven / Gradle / Ivy
/*
* Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Distribution License v. 1.0, which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
package jakarta.xml.bind.annotation;
import org.w3c.dom.Element;
import jakarta.xml.bind.JAXBContext;
import jakarta.xml.bind.JAXBElement;
import jakarta.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import java.util.List;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Maps a JavaBean property to XML infoset representation and/or JAXBElement.
*
*
* This annotation serves as a "catch-all" property while unmarshalling
* xml content into a instance of a Jakarta XML Binding 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 {@link Element}[] others;
*
* // Collection of {@link Element} or JAXBElements.
* @XmlAnyElement(lax="true")
* public {@link Object}[] others;
*
* @XmlAnyElement
* private List<{@link Element}> nodes;
*
* @XmlAnyElement
* private {@link Element} node;
*
*
* Restriction usage constraints
*
* 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.
*
*
Relationship to other annotations
*
* 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;
*
*
*
* Schema To Java example
*
* The following schema would produce the following Java class:
* {@code
*
*
*
*
* }
*
*
* class Foo {
* int a;
* int b;
* @{@link XmlAnyElement}
* List<Element> any;
* }
*
*
* It can unmarshal instances like
*
* {@code
*
* 1
* 5 // this will be bound to DOM, because the annotation doesn't remember namespaces.
*
* }
*
*
*
* The following schema would produce the following Java class:
* {@code
*
*
*
*
*
*
*
* }
*
*
* class Bar extends Foo {
* int c;
* // Foo.getAny() also represents wildcard content for type definition bar.
* }
*
*
*
* It can unmarshal instances like
*
* {@code
*
* 1
* 5 // this now goes to Bar.c
*
* }
*
*
*
*
* Using {@link XmlAnyElement} with {@link XmlElementRef}
*
* 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:
*
{@code
*
*
*
*
* }
*
*
* 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
*
*
*{@code }
*{@code 1} // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
*{@code }
*
*
*
*
*
* 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:
*
* @{@link XmlRootElement}
* class Foo {
* @XmlAnyElement(lax=true)
* public {@link Object}[] others;
* }
*
* then the following document will unmarshal like this:
* {@code
*
*
*
* 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 1.6, JAXB 2.0
*/
@Retention(RUNTIME)
@Target({FIELD,METHOD})
public @interface XmlAnyElement {
/**
* Controls the unmarshaller behavior when it sees elements
* known to the current {@link 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 {@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 Jakarta XML Binding 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 Jakarta XML Binding 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 Jakarta XML Binding 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;
}