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  *    &lt;names> ... &lt;/names>
  48  *    &lt;names> ... &lt;/names>
  49  *
  50  *    // XML Serialization Form 2 ( Wrapped collection )
  51  *    &lt;wrapperElement>
  52  *       &lt;names> value-of-item &lt;/names>
  53  *       &lt;names> value-of-item &lt;/names>
  54  *       ....
  55  *    &lt;/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 }