1 /*
2 * Copyright (c) 2005, 2015, 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 * <h2>Usages:</h2>
54 * <pre>
55 * @XmlAnyElement
56 * public {@link Element}[] others;
57 *
58 * // Collection of {@link Element} or JAXB elements.
59 * @XmlAnyElement(lax="true")
60 * public {@link Object}[] others;
61 *
62 * @XmlAnyElement
63 * private List<{@link Element}> nodes;
64 *
65 * @XmlAnyElement
66 * private {@link Element} node;
67 * </pre>
68 *
69 * <h2>Restriction usage constraints</h2>
70 * <p>
71 * This annotation is mutually exclusive with
72 * {@link XmlElement}, {@link XmlAttribute}, {@link XmlValue},
73 * {@link XmlElements}, {@link XmlID}, and {@link XmlIDREF}.
74 *
75 * <p>
76 * There can be only one {@link XmlAnyElement} annotated JavaBean property
77 * in a class and its super classes.
78 *
79 * <h2>Relationship to other annotations</h2>
80 * <p>
81 * This annotation can be used with {@link XmlJavaTypeAdapter}, so that users
82 * can map their own data structure to DOM, which in turn can be composed
83 * into XML.
84 *
85 * <p>
86 * This annotation can be used with {@link XmlMixed} like this:
87 * <pre>
88 * // List of java.lang.String or DOM nodes.
89 * @XmlAnyElement @XmlMixed
90 * List<Object> others;
91 * </pre>
92 *
93 *
94 * <h2>Schema To Java example</h2>
95 *
96 * The following schema would produce the following Java class:
97 * <pre>
98 * <xs:complexType name="foo">
99 * <xs:sequence>
100 * <xs:element name="a" type="xs:int" />
101 * <xs:element name="b" type="xs:int" />
102 * <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
103 * </xs:sequence>
104 * </xs:complexType>
105 * </pre>
106 *
107 * <pre>
108 * class Foo {
109 * int a;
110 * int b;
111 * @{@link XmlAnyElement}
112 * List<Element> any;
113 * }
114 * </pre>
115 *
116 * It can unmarshal instances like
117 *
118 * <pre>
119 * <foo xmlns:e="extra">
120 * <a>1</a>
121 * <e:other /> // this will be bound to DOM, because unmarshalling is orderless
122 * <b>3</b>
123 * <e:other />
124 * <c>5</c> // this will be bound to DOM, because the annotation doesn't remember namespaces.
125 * </foo>
126 * </pre>
127 *
128 *
129 *
130 * The following schema would produce the following Java class:
131 * <pre>
132 * <xs:complexType name="bar">
133 * <xs:complexContent>
134 * <xs:extension base="foo">
135 * <xs:sequence>
136 * <xs:element name="c" type="xs:int" />
137 * <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
138 * </xs:sequence>
139 * </xs:extension>
140 * </xs:complexType>
141 * </pre>
142 *
143 * <pre>
144 * class Bar extends Foo {
145 * int c;
146 * // Foo.getAny() also represents wildcard content for type definition bar.
147 * }
148 * </pre>
149 *
150 *
151 * It can unmarshal instances like
152 *
153 * <pre>
154 * <bar xmlns:e="extra">
155 * <a>1</a>
156 * <e:other /> // this will be bound to DOM, because unmarshalling is orderless
157 * <b>3</b>
158 * <e:other />
159 * <c>5</c> // this now goes to Bar.c
160 * <e:other /> // this will go to Foo.any
161 * </bar>
162 * </pre>
163 *
164 *
165 *
166 *
167 * <h2>Using {@link XmlAnyElement} with {@link XmlElementRef}</h2>
168 * <p>
169 * The {@link XmlAnyElement} annotation can be used with {@link XmlElementRef}s to
170 * designate additional elements that can participate in the content tree.
171 *
172 * <p>
173 * The following schema would produce the following Java class:
174 * <pre>
175 * <xs:complexType name="foo">
176 * <xs:choice maxOccurs="unbounded" minOccurs="0">
177 * <xs:element name="a" type="xs:int" />
178 * <xs:element name="b" type="xs:int" />
179 * <xs:any namespace="##other" processContents="lax" />
180 * </xs:choice>
181 * </xs:complexType>
182 * </pre>
183 *
184 * <pre>
185 * class Foo {
186 * @{@link XmlAnyElement}(lax="true")
187 * @{@link XmlElementRefs}({
188 * @{@link XmlElementRef}(name="a", type="JAXBElement.class")
189 * @{@link XmlElementRef}(name="b", type="JAXBElement.class")
190 * })
191 * {@link List}<{@link Object}> others;
192 * }
193 *
194 * @XmlRegistry
195 * class ObjectFactory {
196 * ...
197 * @XmlElementDecl(name = "a", namespace = "", scope = Foo.class)
198 * {@link JAXBElement}<Integer> createFooA( Integer i ) { ... }
199 *
200 * @XmlElementDecl(name = "b", namespace = "", scope = Foo.class)
201 * {@link JAXBElement}<Integer> createFooB( Integer i ) { ... }
202 * </pre>
203 *
204 * It can unmarshal instances like
205 *
206 * <pre>
207 * <foo xmlns:e="extra">
208 * <a>1</a> // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
209 * <e:other /> // this will unmarshal to a DOM {@link Element}.
210 * <b>3</b> // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
211 * </foo>
212 * </pre>
213 *
214 *
215 *
216 *
217 * <h2>W3C XML Schema "lax" wildcard emulation</h2>
218 * The lax element of the annotation enables the emulation of the "lax" wildcard semantics.
219 * For example, when the Java source code is annotated like this:
220 * <pre>
221 * @{@link XmlRootElement}
222 * class Foo {
223 * @XmlAnyElement(lax=true)
224 * public {@link Object}[] others;
225 * }
226 * </pre>
227 * then the following document will unmarshal like this:
228 * <pre>
229 * <foo>
230 * <unknown />
231 * <foo />
232 * </foo>
233 *
234 * Foo foo = unmarshal();
235 * // 1 for 'unknown', another for 'foo'
236 * assert foo.others.length==2;
237 * // 'unknown' unmarshals to a DOM element
238 * assert foo.others[0] instanceof Element;
239 * // because of lax=true, the 'foo' element eagerly
240 * // unmarshals to a Foo object.
241 * assert foo.others[1] instanceof Foo;
242 * </pre>
243 *
244 * @author Kohsuke Kawaguchi
245 * @since 1.6, JAXB 2.0
246 */
247 @Retention(RUNTIME)
248 @Target({FIELD,METHOD})
249 public @interface XmlAnyElement {
250
251 /**
252 * Controls the unmarshaller behavior when it sees elements
253 * known to the current {@link JAXBContext}.
254 *
255 * <h3>When false</h3>
256 * <p>
257 * If false, all the elements that match the property will be unmarshalled
258 * to DOM, and the property will only contain DOM elements.
259 *
260 * <h3>When true</h3>
261 * <p>
262 * If true, when an element matches a property marked with {@link XmlAnyElement}
263 * is known to {@link JAXBContext} (for example, there's a class with
264 * {@link XmlRootElement} that has the same tag name, or there's
265 * {@link XmlElementDecl} that has the same tag name),
266 * the unmarshaller will eagerly unmarshal this element to the JAXB object,
267 * instead of unmarshalling it to DOM. Additionally, if the element is
268 * unknown but it has a known xsi:type, the unmarshaller eagerly unmarshals
269 * the element to a {@link JAXBElement}, with the unknown element name and
270 * the JAXBElement value is set to an instance of the JAXB mapping of the
271 * known xsi:type.
272 *
273 * <p>
274 * As a result, after the unmarshalling, the property can become heterogeneous;
275 * it can have both DOM nodes and some JAXB objects at the same time.
276 *
277 * <p>
278 * This can be used to emulate the "lax" wildcard semantics of the W3C XML Schema.
279 */
280 boolean lax() default false;
281
282 /**
283 * Specifies the {@link DomHandler} which is responsible for actually
284 * converting XML from/to a DOM-like data structure.
285 */
286 Class<? extends DomHandler> value() default W3CDomHandler.class;
287 }