001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.bind.annotation;
027
028 import org.w3c.dom.Element;
029
030 import javax.xml.bind.JAXBContext;
031 import javax.xml.bind.JAXBElement;
032 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
033 import javax.xml.bind.annotation.*;
034 import java.lang.annotation.Retention;
035 import java.lang.annotation.Target;
036 import java.util.List;
037
038 import static java.lang.annotation.ElementType.FIELD;
039 import static java.lang.annotation.ElementType.METHOD;
040 import static java.lang.annotation.RetentionPolicy.RUNTIME;
041
042 /**
043 * Maps a JavaBean property to XML infoset representation and/or JAXB element.
044 *
045 * <p>
046 * This annotation serves as a "catch-all" property while unmarshalling
047 * xml content into a instance of a JAXB annotated class. It typically
048 * annotates a multi-valued JavaBean property, but it can occur on
049 * single value JavaBean property. During unmarshalling, each xml element
050 * that does not match a static @XmlElement or @XmlElementRef
051 * annotation for the other JavaBean properties on the class, is added to this
052 * "catch-all" property.
053 *
054 * <p>
055 * <h2>Usages:</h2>
056 * <pre>
057 * @XmlAnyElement
058 * public {@link Element}[] others;
059 *
060 * // Collection of {@link Element} or JAXB elements.
061 * @XmlAnyElement(lax="true")
062 * public {@link Object}[] others;
063 *
064 * @XmlAnyElement
065 * private List<{@link Element}> nodes;
066 *
067 * @XmlAnyElement
068 * private {@link Element} node;
069 * </pre>
070 *
071 * <h2>Restriction usage constraints</h2>
072 * <p>
073 * This annotation is mutually exclusive with
074 * {@link XmlElement}, {@link XmlAttribute}, {@link XmlValue},
075 * {@link XmlElements}, {@link XmlID}, and {@link XmlIDREF}.
076 *
077 * <p>
078 * There can be only one {@link XmlAnyElement} annotated JavaBean property
079 * in a class and its super classes.
080 *
081 * <h2>Relationship to other annotations</h2>
082 * <p>
083 * This annotation can be used with {@link XmlJavaTypeAdapter}, so that users
084 * can map their own data structure to DOM, which in turn can be composed
085 * into XML.
086 *
087 * <p>
088 * This annotation can be used with {@link XmlMixed} like this:
089 * <pre>
090 * // List of java.lang.String or DOM nodes.
091 * @XmlAnyElement @XmlMixed
092 * List<Object> others;
093 * </pre>
094 *
095 *
096 * <h2>Schema To Java example</h2>
097 *
098 * The following schema would produce the following Java class:
099 * <pre><xmp>
100 * <xs:complexType name="foo">
101 * <xs:sequence>
102 * <xs:element name="a" type="xs:int" />
103 * <xs:element name="b" type="xs:int" />
104 * <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
105 * </xs:sequence>
106 * </xs:complexType>
107 * </xmp></pre>
108 *
109 * <pre>
110 * class Foo {
111 * int a;
112 * int b;
113 * @{@link XmlAnyElement}
114 * List<Element> any;
115 * }
116 * </pre>
117 *
118 * It can unmarshal instances like
119 *
120 * <pre><xmp>
121 * <foo xmlns:e="extra">
122 * <a>1</a>
123 * <e:other /> // this will be bound to DOM, because unmarshalling is orderless
124 * <b>3</b>
125 * <e:other />
126 * <c>5</c> // this will be bound to DOM, because the annotation doesn't remember namespaces.
127 * </foo>
128 * </xmp></pre>
129 *
130 *
131 *
132 * The following schema would produce the following Java class:
133 * <pre><xmp>
134 * <xs:complexType name="bar">
135 * <xs:complexContent>
136 * <xs:extension base="foo">
137 * <xs:sequence>
138 * <xs:element name="c" type="xs:int" />
139 * <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
140 * </xs:sequence>
141 * </xs:extension>
142 * </xs:complexType>
143 * </xmp></pre>
144 *
145 * <pre><xmp>
146 * class Bar extends Foo {
147 * int c;
148 * // Foo.getAny() also represents wildcard content for type definition bar.
149 * }
150 * </xmp></pre>
151 *
152 *
153 * It can unmarshal instances like
154 *
155 * <pre><xmp>
156 * <bar xmlns:e="extra">
157 * <a>1</a>
158 * <e:other /> // this will be bound to DOM, because unmarshalling is orderless
159 * <b>3</b>
160 * <e:other />
161 * <c>5</c> // this now goes to Bar.c
162 * <e:other /> // this will go to Foo.any
163 * </bar>
164 * </xmp></pre>
165 *
166 *
167 *
168 *
169 * <h2>Using {@link XmlAnyElement} with {@link XmlElementRef}</h2>
170 * <p>
171 * The {@link XmlAnyElement} annotation can be used with {@link XmlElementRef}s to
172 * designate additional elements that can participate in the content tree.
173 *
174 * <p>
175 * The following schema would produce the following Java class:
176 * <pre><xmp>
177 * <xs:complexType name="foo">
178 * <xs:choice maxOccurs="unbounded" minOccurs="0">
179 * <xs:element name="a" type="xs:int" />
180 * <xs:element name="b" type="xs:int" />
181 * <xs:any namespace="##other" processContents="lax" />
182 * </xs:choice>
183 * </xs:complexType>
184 * </xmp></pre>
185 *
186 * <pre>
187 * class Foo {
188 * @{@link XmlAnyElement}(lax="true")
189 * @{@link XmlElementRefs}({
190 * @{@link XmlElementRef}(name="a", type="JAXBElement.class")
191 * @{@link XmlElementRef}(name="b", type="JAXBElement.class")
192 * })
193 * {@link List}<{@link Object}> others;
194 * }
195 *
196 * @XmlRegistry
197 * class ObjectFactory {
198 * ...
199 * @XmlElementDecl(name = "a", namespace = "", scope = Foo.class)
200 * {@link JAXBElement}<Integer> createFooA( Integer i ) { ... }
201 *
202 * @XmlElementDecl(name = "b", namespace = "", scope = Foo.class)
203 * {@link JAXBElement}<Integer> createFooB( Integer i ) { ... }
204 * </pre>
205 *
206 * It can unmarshal instances like
207 *
208 * <pre><xmp>
209 * <foo xmlns:e="extra">
210 * <a>1</a> // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
211 * <e:other /> // this will unmarshal to a DOM {@link Element}.
212 * <b>3</b> // this will unmarshal to a {@link JAXBElement} instance whose value is 1.
213 * </foo>
214 * </xmp></pre>
215 *
216 *
217 *
218 *
219 * <h2>W3C XML Schema "lax" wildcard emulation</h2>
220 * The lax element of the annotation enables the emulation of the "lax" wildcard semantics.
221 * For example, when the Java source code is annotated like this:
222 * <pre>
223 * @{@link XmlRootElement}
224 * class Foo {
225 * @XmlAnyElement(lax=true)
226 * public {@link Object}[] others;
227 * }
228 * </pre>
229 * then the following document will unmarshal like this:
230 * <pre><xmp>
231 * <foo>
232 * <unknown />
233 * <foo />
234 * </foo>
235 *
236 * Foo foo = unmarshal();
237 * // 1 for 'unknown', another for 'foo'
238 * assert foo.others.length==2;
239 * // 'unknown' unmarshals to a DOM element
240 * assert foo.others[0] instanceof Element;
241 * // because of lax=true, the 'foo' element eagerly
242 * // unmarshals to a Foo object.
243 * assert foo.others[1] instanceof Foo;
244 * </xmp></pre>
245 *
246 *
247 * @author Kohsuke Kawaguchi
248 * @since JAXB2.0
249 */
250 @Retention(RUNTIME)
251 @Target({FIELD,METHOD})
252 public @interface XmlAnyElement {
253
254 /**
255 * Controls the unmarshaller behavior when it sees elements
256 * known to the current {@link JAXBContext}.
257 *
258 * <h3>When false</h3>
259 * <p>
260 * If false, all the elements that match the property will be unmarshalled
261 * to DOM, and the property will only contain DOM elements.
262 *
263 * <h3>When true</h3>
264 * <p>
265 * If true, when an element matches a property marked with {@link XmlAnyElement}
266 * is known to {@link JAXBContext} (for example, there's a class with
267 * {@link XmlRootElement} that has the same tag name, or there's
268 * {@link XmlElementDecl} that has the same tag name),
269 * the unmarshaller will eagerly unmarshal this element to the JAXB object,
270 * instead of unmarshalling it to DOM. Additionally, if the element is
271 * unknown but it has a known xsi:type, the unmarshaller eagerly unmarshals
272 * the element to a {@link JAXBElement}, with the unknown element name and
273 * the JAXBElement value is set to an instance of the JAXB mapping of the
274 * known xsi:type.
275 *
276 * <p>
277 * As a result, after the unmarshalling, the property can become heterogeneous;
278 * it can have both DOM nodes and some JAXB objects at the same time.
279 *
280 * <p>
281 * This can be used to emulate the "lax" wildcard semantics of the W3C XML Schema.
282 */
283 boolean lax() default false;
284
285 /**
286 * Specifies the {@link DomHandler} which is responsible for actually
287 * converting XML from/to a DOM-like data structure.
288 */
289 Class<? extends DomHandler> value() default W3CDomHandler.class;
290 }
|