jdk8-mips64-public/jaxws: src/share/jaxws_classes/javax/xml/bind/annotation/XmlElementWrapper.java@9c07ef4934dd

     1 /*

     2  * Copyright (c) 2005, 2013, 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  */

    26 package javax.xml.bind.annotation;

    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;

    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  */

    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";

   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";

   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;

   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 }

Mercurial > jdk8-mips64-public > jaxws / file revision