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
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
|
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
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
|