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 @XmlElement or @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 * @XmlAnyElement
57 * public {@link Element}[] others;
58 *
59 * // Collection of {@link Element} or JAXB elements.
60 * @XmlAnyElement(lax="true")
61 * public {@link Object}[] others;
62 *
63 * @XmlAnyElement
64 * private List<{@link Element}> nodes;
65 *
66 * @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 * @XmlAnyElement @XmlMixed
91 * List<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 * <xs:complexType name="foo">
100 * <xs:sequence>
101 * <xs:element name="a" type="xs:int" />
102 * <xs:element name="b" type="xs:int" />
103 * <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
104 * </xs:sequence>
105 * </xs:complexType>
106 * </pre>
107 *
108 * <pre>
109 * class Foo {
110 * int a;
111 * int b;
112 * @{@link XmlAnyElement}
113 * List<Element> any;
114 * }
115 * </pre>
116 *
117 * It can unmarshal instances like
118 *
119 * <pre>
120 * <foo xmlns:e="extra">
121 * <a>1</a>
122 * <e:other /> // this will be bound to DOM, because unmarshalling is orderless
123 * <b>3</b>
124 * <e:other />
125 * <c>5</c> // this will be bound to DOM, because the annotation doesn't remember namespaces.
126 * </foo>
127 * </pre>
128 *
129 *
130 *
131 * The following schema would produce the following Java class:
132 * <pre>
133 * <xs:complexType name="bar">
134 * <xs:complexContent>
135 * <xs:extension base="foo">
136 * <xs:sequence>
137 * <xs:element name="c" type="xs:int" />
138 * <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
139 * </xs:sequence>
140 * </xs:extension>
141 * </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 * <bar xmlns:e="extra">
156 * <a>1</a>
157 * <e:other /> // this will be bound to DOM, because unmarshalling is orderless
158 * <b>3</b>
159 * <e:other />
160 * <c>5</c> // this now goes to Bar.c
161 * <e:other /> // this will go to Foo.any
162 * </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 * <xs:complexType name="foo">
177 * <xs:choice maxOccurs="unbounded" minOccurs="0">
178 * <xs:element name="a" type="xs:int" />
179 * <xs:element name="b" type="xs:int" />
180 * <xs:any namespace="##other" processContents="lax" />
181 * </xs:choice>
182 * </xs:complexType>
183 * </pre>
184 *
185 * <pre>
186 * class Foo {
187 * @{@link XmlAnyElement}(lax="true")
188 * @{@link XmlElementRefs}({
189 * @{@link XmlElementRef}(name="a", type="JAXBElement.class")
190 * @{@link XmlElementRef}(name="b", type="JAXBElement.class")
191 * })
192 * {@link List}<{@link Object}> others;
193 * }
194 *
195 * @XmlRegistry
196 * class ObjectFactory {
197 * ...
198 * @XmlElementDecl(name = "a", namespace = "", scope = Foo.class)
199 * {@link JAXBElement}<Integer> createFooA( Integer i ) { ... }
200 *
201 * @XmlElementDecl(name = "b", namespace = "", scope = Foo.class)
202 * {@link JAXBElement}<Integer> createFooB( Integer i ) { ... }
203 * </pre>
204 *
205 * It can unmarshal instances like
206 *
207 * <pre>
208 * <foo xmlns:e="extra">
209 * <a>1</a> // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
210 * <e:other /> // this will unmarshal to a DOM {@link Element}.
211 * <b>3</b> // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
212 * </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 * @{@link XmlRootElement}
223 * class Foo {
224 * @XmlAnyElement(lax=true)
225 * public {@link Object}[] others;
226 * }
227 * </pre>
228 * then the following document will unmarshal like this:
229 * <pre>
230 * <foo>
231 * <unknown />
232 * <foo />
233 * </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 1.6, JAXB 2.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 }