1 /* 2 * Copyright (c) 2005, 2011, 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 26 package javax.xml.bind.annotation; 27 28 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter; 29 import static java.lang.annotation.RetentionPolicy.RUNTIME; 30 import static java.lang.annotation.ElementType.FIELD; 31 import static java.lang.annotation.ElementType.METHOD; 32 import java.lang.annotation.Retention; 33 import java.lang.annotation.Target; 34 35 /** 36 * Generates a wrapper element around XML representation. 37 * 38 * This is primarily intended to be used to produce a wrapper 39 * XML element around collections. The annotation therefore supports 40 * two forms of serialization shown below. 41 * 42 * <pre> 43 * //Example: code fragment 44 * int[] names; 45 * 46 * // XML Serialization Form 1 (Unwrapped collection) 47 * <names> ... </names> 48 * <names> ... </names> 49 * 50 * // XML Serialization Form 2 ( Wrapped collection ) 51 * <wrapperElement> 52 * <names> value-of-item </names> 53 * <names> value-of-item </names> 54 * .... 55 * </wrapperElement> 56 * </pre> 57 * 58 * <p> The two serialized XML forms allow a null collection to be 59 * represented either by absence or presence of an element with a 60 * nillable attribute. 61 * 62 * <p> <b>Usage</b> </p> 63 * <p> 64 * The <tt>@XmlElementWrapper</tt> annotation can be used with the 65 * following program elements: 66 * <ul> 67 * <li> JavaBean property </li> 68 * <li> non static, non transient field </li> 69 * </ul> 70 * 71 * <p>The usage is subject to the following constraints: 72 * <ul> 73 * <li> The property must be a collection property </li> 74 * <li> This annotation can be used with the following annotations: 75 * {@link XmlElement}, 76 * {@link XmlElements}, 77 * {@link XmlElementRef}, 78 * {@link XmlElementRefs}, 79 * {@link XmlJavaTypeAdapter}.</li> 80 * </ul> 81 * 82 * <p>See "Package Specification" in javax.xml.bind.package javadoc for 83 * additional common information.</p> 84 * 85 * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li></ul> 86 * @see XmlElement 87 * @see XmlElements 88 * @see XmlElementRef 89 * @see XmlElementRefs 90 * @since JAXB2.0 91 * 92 */ 93 94 @Retention(RUNTIME) @Target({FIELD, METHOD}) 95 public @interface XmlElementWrapper { 96 /** 97 * Name of the XML wrapper element. By default, the XML wrapper 98 * element name is derived from the JavaBean property name. 99 */ 100 String name() default "##default"; 101 102 /** 103 * XML target namespace of the XML wrapper element. 104 * <p> 105 * If the value is "##default", then the namespace is determined 106 * as follows: 107 * <ol> 108 * <li> 109 * If the enclosing package has {@link XmlSchema} annotation, 110 * and its {@link XmlSchema#elementFormDefault() elementFormDefault} 111 * is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of 112 * the enclosing class. 113 * 114 * <li> 115 * Otherwise "" (which produces unqualified element in the default 116 * namespace. 117 * </ol> 118 */ 119 String namespace() default "##default"; 120 121 /** 122 * If true, the absence of the collection is represented by 123 * using <tt>xsi:nil='true'</tt>. Otherwise, it is represented by 124 * the absence of the element. 125 */ 126 boolean nillable() default false; 127 128 /** 129 * Customize the wrapper element declaration to be required. 130 * 131 * <p> 132 * If required() is true, then the corresponding generated 133 * XML schema element declaration will have <tt>minOccurs="1"</tt>, 134 * to indicate that the wrapper element is always expected. 135 * 136 * <p> 137 * Note that this only affects the schema generation, and 138 * not the unmarshalling or marshalling capability. This is 139 * simply a mechanism to let users express their application constraints 140 * better. 141 * 142 * @since JAXB 2.1 143 */ 144 boolean required() default false; 145 }