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 26package javax.xml.bind.annotation; 27 28import org.w3c.dom.Element; 29 30import javax.xml.bind.JAXBContext; 31import javax.xml.bind.JAXBElement; 32import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter; 33import java.lang.annotation.Retention; 34import java.lang.annotation.Target; 35import java.util.List; 36 37import static java.lang.annotation.ElementType.FIELD; 38import static java.lang.annotation.ElementType.METHOD; 39import 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>{@code 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>{@code 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>{@code 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>{@code 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>{@code 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 *{@code <foo xmlns:e="extra">} 208 *{@code <a>1</a>} // this will unmarshal to a {@link JAXBElement} instance whose value is 1. 209 *{@code <e:other />} // this will unmarshal to a DOM {@link Element}. 210 *{@code <b>3</b>} // this will unmarshal to a {@link JAXBElement} instance whose value is 1. 211 *{@code </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>{@code 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}) 249public @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} 288