001: /*
002: * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.bind.annotation;
007:
008: import org.w3c.dom.Element;
009:
010: import javax.xml.bind.JAXBContext;
011: import javax.xml.bind.JAXBElement;
012: import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
013: import javax.xml.bind.annotation.*;
014: import java.lang.annotation.Retention;
015: import java.lang.annotation.Target;
016: import java.util.List;
017:
018: import static java.lang.annotation.ElementType.FIELD;
019: import static java.lang.annotation.ElementType.METHOD;
020: import static java.lang.annotation.RetentionPolicy.RUNTIME;
021:
022: /**
023: * Maps a JavaBean property to XML infoset representation and/or JAXB element.
024: *
025: * <p>
026: * This annotation serves as a "catch-all" property while unmarshalling
027: * xml content into a instance of a JAXB annotated class. It typically
028: * annotates a multi-valued JavaBean property, but it can occur on
029: * single value JavaBean property. During unmarshalling, each xml element
030: * that does not match a static @XmlElement or @XmlElementRef
031: * annotation for the other JavaBean properties on the class, is added to this
032: * "catch-all" property.
033: *
034: * <p>
035: * <h2>Usages:</h2>
036: * <pre>
037: * @XmlAnyElement
038: * public {@link Element}[] others;
039: *
040: * // Collection of {@link Element} or JAXB elements.
041: * @XmlAnyElement(lax="true")
042: * public {@link Object}[] others;
043: *
044: * @XmlAnyElement
045: * private List<{@link Element}> nodes;
046: *
047: * @XmlAnyElement
048: * private {@link Element} node;
049: * </pre>
050: *
051: * <h2>Restriction usage constraints</h2>
052: * <p>
053: * This annotation is mutually exclusive with
054: * {@link XmlElement}, {@link XmlAttribute}, {@link XmlValue},
055: * {@link XmlElements}, {@link XmlID}, and {@link XmlIDREF}.
056: *
057: * <p>
058: * There can be only one {@link XmlAnyElement} annotated JavaBean property
059: * in a class and its super classes.
060: *
061: * <h2>Relationship to other annotations</h2>
062: * <p>
063: * This annotation can be used with {@link XmlJavaTypeAdapter}, so that users
064: * can map their own data structure to DOM, which in turn can be composed
065: * into XML.
066: *
067: * <p>
068: * This annotation can be used with {@link XmlMixed} like this:
069: * <pre>
070: * // List of java.lang.String or DOM nodes.
071: * @XmlAnyElement @XmlMixed
072: * List<Object> others;
073: * </pre>
074: *
075: *
076: * <h2>Schema To Java example</h2>
077: *
078: * The following schema would produce the following Java class:
079: * <pre><xmp>
080: * <xs:complexType name="foo">
081: * <xs:sequence>
082: * <xs:element name="a" type="xs:int" />
083: * <xs:element name="b" type="xs:int" />
084: * <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
085: * </xs:sequence>
086: * </xs:complexType>
087: * </xmp></pre>
088: *
089: * <pre>
090: * class Foo {
091: * int a;
092: * int b;
093: * @{@link XmlAnyElement}
094: * List<Element> any;
095: * }
096: * </pre>
097: *
098: * It can unmarshal instances like
099: *
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: * @{@link XmlAnyElement}(lax="true")
169: * @{@link XmlElementRefs}({
170: * @{@link XmlElementRef}(name="a", type="JAXBElement.class")
171: * @{@link XmlElementRef}(name="b", type="JAXBElement.class")
172: * })
173: * {@link List}<{@link Object}> others;
174: * }
175: *
176: * @XmlRegistry
177: * class ObjectFactory {
178: * ...
179: * @XmlElementDecl(name = "a", namespace = "", scope = Foo.class)
180: * {@link JAXBElement}<Integer> createFooA( Integer i ) { ... }
181: *
182: * @XmlElementDecl(name = "b", namespace = "", scope = Foo.class)
183: * {@link JAXBElement}<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: * @{@link XmlRootElement}
204: * class Foo {
205: * @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: }
|