View Javadoc
1   /*
2    * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.xml.bind.annotation;
27  
28  import org.w3c.dom.Element;
29  
30  import javax.xml.bind.JAXBContext;
31  import javax.xml.bind.JAXBElement;
32  import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
33  import java.lang.annotation.Retention;
34  import java.lang.annotation.Target;
35  import java.util.List;
36  
37  import static java.lang.annotation.ElementType.FIELD;
38  import static java.lang.annotation.ElementType.METHOD;
39  import static java.lang.annotation.RetentionPolicy.RUNTIME;
40  
41  /**
42   * Maps a JavaBean property to XML infoset representation and/or JAXB element.
43   *
44   * <p>
45   * This annotation serves as a "catch-all" property while unmarshalling
46   * xml content into a instance of a JAXB annotated class. It typically
47   * annotates a multi-valued JavaBean property, but it can occur on
48   * single value JavaBean property. During unmarshalling, each xml element
49   * that does not match a static &#64;XmlElement or &#64;XmlElementRef
50   * annotation for the other JavaBean properties on the class, is added to this
51   * "catch-all" property.
52   *
53   * <p>
54   * <h2>Usages:</h2>
55   * <pre>
56   * &#64;XmlAnyElement
57   * public {@link Element}[] others;
58   *
59   * // Collection of {@link Element} or JAXB elements.
60   * &#64;XmlAnyElement(lax="true")
61   * public {@link Object}[] others;
62   *
63   * &#64;XmlAnyElement
64   * private List&lt;{@link Element}> nodes;
65   *
66   * &#64;XmlAnyElement
67   * private {@link Element} node;
68   * </pre>
69   *
70   * <h2>Restriction usage constraints</h2>
71   * <p>
72   * This annotation is mutually exclusive with
73   * {@link XmlElement}, {@link XmlAttribute}, {@link XmlValue},
74   * {@link XmlElements}, {@link XmlID}, and {@link XmlIDREF}.
75   *
76   * <p>
77   * There can be only one {@link XmlAnyElement} annotated JavaBean property
78   * in a class and its super classes.
79   *
80   * <h2>Relationship to other annotations</h2>
81   * <p>
82   * This annotation can be used with {@link XmlJavaTypeAdapter}, so that users
83   * can map their own data structure to DOM, which in turn can be composed
84   * into XML.
85   *
86   * <p>
87   * This annotation can be used with {@link XmlMixed} like this:
88   * <pre>
89   * // List of java.lang.String or DOM nodes.
90   * &#64;XmlAnyElement &#64;XmlMixed
91   * List&lt;Object> others;
92   * </pre>
93   *
94   *
95   * <h2>Schema To Java example</h2>
96   *
97   * The following schema would produce the following Java class:
98   * <pre>
99   * &lt;xs:complexType name="foo">
100  *   &lt;xs:sequence>
101  *     &lt;xs:element name="a" type="xs:int" />
102  *     &lt;xs:element name="b" type="xs:int" />
103  *     &lt;xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
104  *   &lt;/xs:sequence>
105  * &lt;/xs:complexType>
106  * </pre>
107  *
108  * <pre>
109  * class Foo {
110  *   int a;
111  *   int b;
112  *   &#64;{@link XmlAnyElement}
113  *   List&lt;Element> any;
114  * }
115  * </pre>
116  *
117  * It can unmarshal instances like
118  *
119  * <pre>
120  * &lt;foo xmlns:e="extra">
121  *   &lt;a>1</a>
122  *   &lt;e:other />  // this will be bound to DOM, because unmarshalling is orderless
123  *   &lt;b>3</b>
124  *   &lt;e:other />
125  *   &lt;c>5</c>     // this will be bound to DOM, because the annotation doesn't remember namespaces.
126  * &lt;/foo>
127  * </pre>
128  *
129  *
130  *
131  * The following schema would produce the following Java class:
132  * <pre>
133  * &lt;xs:complexType name="bar">
134  *   &lt;xs:complexContent>
135  *   &lt;xs:extension base="foo">
136  *     &lt;xs:sequence>
137  *       &lt;xs:element name="c" type="xs:int" />
138  *       &lt;xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
139  *     &lt;/xs:sequence>
140  *   &lt;/xs:extension>
141  * &lt;/xs:complexType>
142  * </pre>
143  *
144  * <pre>
145  * class Bar extends Foo {
146  *   int c;
147  *   // Foo.getAny() also represents wildcard content for type definition bar.
148  * }
149  * </pre>
150  *
151  *
152  * It can unmarshal instances like
153  *
154  * <pre>
155  * &lt;bar xmlns:e="extra">
156  *   &lt;a>1</a>
157  *   &lt;e:other />  // this will be bound to DOM, because unmarshalling is orderless
158  *   &lt;b>3</b>
159  *   &lt;e:other />
160  *   &lt;c>5</c>     // this now goes to Bar.c
161  *   &lt;e:other />  // this will go to Foo.any
162  * &lt;/bar>
163  * </pre>
164  *
165  *
166  *
167  *
168  * <h2>Using {@link XmlAnyElement} with {@link XmlElementRef}</h2>
169  * <p>
170  * The {@link XmlAnyElement} annotation can be used with {@link XmlElementRef}s to
171  * designate additional elements that can participate in the content tree.
172  *
173  * <p>
174  * The following schema would produce the following Java class:
175  * <pre>
176  * &lt;xs:complexType name="foo">
177  *   &lt;xs:choice maxOccurs="unbounded" minOccurs="0">
178  *     &lt;xs:element name="a" type="xs:int" />
179  *     &lt;xs:element name="b" type="xs:int" />
180  *     &lt;xs:any namespace="##other" processContents="lax" />
181  *   &lt;/xs:choice>
182  * &lt;/xs:complexType>
183  * </pre>
184  *
185  * <pre>
186  * class Foo {
187  *   &#64;{@link XmlAnyElement}(lax="true")
188  *   &#64;{@link XmlElementRefs}({
189  *     &#64;{@link XmlElementRef}(name="a", type="JAXBElement.class")
190  *     &#64;{@link XmlElementRef}(name="b", type="JAXBElement.class")
191  *   })
192  *   {@link List}&lt;{@link Object}> others;
193  * }
194  *
195  * &#64;XmlRegistry
196  * class ObjectFactory {
197  *   ...
198  *   &#64;XmlElementDecl(name = "a", namespace = "", scope = Foo.class)
199  *   {@link JAXBElement}&lt;Integer> createFooA( Integer i ) { ... }
200  *
201  *   &#64;XmlElementDecl(name = "b", namespace = "", scope = Foo.class)
202  *   {@link JAXBElement}&lt;Integer> createFooB( Integer i ) { ... }
203  * </pre>
204  *
205  * It can unmarshal instances like
206  *
207  * <pre>
208  * &lt;foo xmlns:e="extra">
209  *   &lt;a>1</a>     // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
210  *   &lt;e:other />  // this will unmarshal to a DOM {@link Element}.
211  *   &lt;b>3</b>     // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
212  * &lt;/foo>
213  * </pre>
214  *
215  *
216  *
217  *
218  * <h2>W3C XML Schema "lax" wildcard emulation</h2>
219  * The lax element of the annotation enables the emulation of the "lax" wildcard semantics.
220  * For example, when the Java source code is annotated like this:
221  * <pre>
222  * &#64;{@link XmlRootElement}
223  * class Foo {
224  *   &#64;XmlAnyElement(lax=true)
225  *   public {@link Object}[] others;
226  * }
227  * </pre>
228  * then the following document will unmarshal like this:
229  * <pre>
230  * &lt;foo>
231  *   &lt;unknown />
232  *   &lt;foo />
233  * &lt;/foo>
234  *
235  * Foo foo = unmarshal();
236  * // 1 for 'unknown', another for 'foo'
237  * assert foo.others.length==2;
238  * // 'unknown' unmarshals to a DOM element
239  * assert foo.others[0] instanceof Element;
240  * // because of lax=true, the 'foo' element eagerly
241  * // unmarshals to a Foo object.
242  * assert foo.others[1] instanceof Foo;
243  * </pre>
244  *
245  * @author Kohsuke Kawaguchi
246  * @since JAXB2.0
247  */
248 @Retention(RUNTIME)
249 @Target({FIELD,METHOD})
250 public @interface XmlAnyElement {
251 
252     /**
253      * Controls the unmarshaller behavior when it sees elements
254      * known to the current {@link JAXBContext}.
255      *
256      * <h3>When false</h3>
257      * <p>
258      * If false, all the elements that match the property will be unmarshalled
259      * to DOM, and the property will only contain DOM elements.
260      *
261      * <h3>When true</h3>
262      * <p>
263      * If true, when an element matches a property marked with {@link XmlAnyElement}
264      * is known to {@link JAXBContext} (for example, there's a class with
265      * {@link XmlRootElement} that has the same tag name, or there's
266      * {@link XmlElementDecl} that has the same tag name),
267      * the unmarshaller will eagerly unmarshal this element to the JAXB object,
268      * instead of unmarshalling it to DOM. Additionally, if the element is
269      * unknown but it has a known xsi:type, the unmarshaller eagerly unmarshals
270      * the element to a {@link JAXBElement}, with the unknown element name and
271      * the JAXBElement value is set to an instance of the JAXB mapping of the
272      * known xsi:type.
273      *
274      * <p>
275      * As a result, after the unmarshalling, the property can become heterogeneous;
276      * it can have both DOM nodes and some JAXB objects at the same time.
277      *
278      * <p>
279      * This can be used to emulate the "lax" wildcard semantics of the W3C XML Schema.
280      */
281     boolean lax() default false;
282 
283     /**
284      * Specifies the {@link DomHandler} which is responsible for actually
285      * converting XML from/to a DOM-like data structure.
286      */
287     Class<? extends DomHandler> value() default W3CDomHandler.class;
288 }