XmlAnyElement


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