325N/A/*
325N/A * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
325N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
325N/A *
325N/A * This code is free software; you can redistribute it and/or modify it
325N/A * under the terms of the GNU General Public License version 2 only, as
325N/A * published by the Free Software Foundation. Oracle designates this
325N/A * particular file as subject to the "Classpath" exception as provided
325N/A * by Oracle in the LICENSE file that accompanied this code.
325N/A *
325N/A * This code is distributed in the hope that it will be useful, but WITHOUT
325N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
325N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
325N/A * version 2 for more details (a copy is included in the LICENSE file that
325N/A * accompanied this code).
325N/A *
325N/A * You should have received a copy of the GNU General Public License version
325N/A * 2 along with this work; if not, write to the Free Software Foundation,
325N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
325N/A *
325N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
325N/A * or visit www.oracle.com if you need additional information or have any
325N/A * questions.
325N/A */
325N/A
325N/Apackage javax.xml.bind.annotation;
325N/A
325N/Aimport javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
325N/Aimport static java.lang.annotation.RetentionPolicy.RUNTIME;
325N/Aimport static java.lang.annotation.ElementType.FIELD;
325N/Aimport static java.lang.annotation.ElementType.METHOD;
325N/Aimport java.lang.annotation.Retention;
325N/Aimport java.lang.annotation.Target;
325N/A
325N/A/**
325N/A * Generates a wrapper element around XML representation.
325N/A *
325N/A * This is primarily intended to be used to produce a wrapper
325N/A * XML element around collections. The annotation therefore supports
325N/A * two forms of serialization shown below.
325N/A *
325N/A * <pre>
325N/A * //Example: code fragment
325N/A * int[] names;
325N/A *
325N/A * // XML Serialization Form 1 (Unwrapped collection)
325N/A * &lt;names> ... &lt;/names>
325N/A * &lt;names> ... &lt;/names>
325N/A *
325N/A * // XML Serialization Form 2 ( Wrapped collection )
325N/A * &lt;wrapperElement>
325N/A * &lt;names> value-of-item &lt;/names>
325N/A * &lt;names> value-of-item &lt;/names>
325N/A * ....
325N/A * &lt;/wrapperElement>
325N/A * </pre>
325N/A *
325N/A * <p> The two serialized XML forms allow a null collection to be
325N/A * represented either by absence or presence of an element with a
325N/A * nillable attribute.
325N/A *
325N/A * <p> <b>Usage</b> </p>
325N/A * <p>
325N/A * The <tt>@XmlElementWrapper</tt> annotation can be used with the
325N/A * following program elements:
325N/A * <ul>
325N/A * <li> JavaBean property </li>
325N/A * <li> non static, non transient field </li>
325N/A * </ul>
325N/A *
325N/A * <p>The usage is subject to the following constraints:
325N/A * <ul>
325N/A * <li> The property must be a collection property </li>
325N/A * <li> This annotation can be used with the following annotations:
325N/A * {@link XmlElement},
325N/A * {@link XmlElements},
325N/A * {@link XmlElementRef},
325N/A * {@link XmlElementRefs},
325N/A * {@link XmlJavaTypeAdapter}.</li>
325N/A * </ul>
325N/A *
325N/A * <p>See "Package Specification" in javax.xml.bind.package javadoc for
325N/A * additional common information.</p>
325N/A *
325N/A * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li></ul>
325N/A * @see XmlElement
325N/A * @see XmlElements
325N/A * @see XmlElementRef
325N/A * @see XmlElementRefs
325N/A * @since JAXB2.0
325N/A *
325N/A */
325N/A
325N/A@Retention(RUNTIME) @Target({FIELD, METHOD})
325N/Apublic @interface XmlElementWrapper {
325N/A /**
325N/A * Name of the XML wrapper element. By default, the XML wrapper
325N/A * element name is derived from the JavaBean property name.
325N/A */
325N/A String name() default "##default";
325N/A
325N/A /**
325N/A * XML target namespace of the XML wrapper element.
325N/A * <p>
325N/A * If the value is "##default", then the namespace is determined
325N/A * as follows:
325N/A * <ol>
325N/A * <li>
325N/A * If the enclosing package has {@link XmlSchema} annotation,
325N/A * and its {@link XmlSchema#elementFormDefault() elementFormDefault}
325N/A * is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of
325N/A * the enclosing class.
325N/A *
325N/A * <li>
325N/A * Otherwise "" (which produces unqualified element in the default
325N/A * namespace.
325N/A * </ol>
325N/A */
325N/A String namespace() default "##default";
325N/A
325N/A /**
325N/A * If true, the absence of the collection is represented by
325N/A * using <tt>xsi:nil='true'</tt>. Otherwise, it is represented by
325N/A * the absence of the element.
325N/A */
325N/A boolean nillable() default false;
325N/A
325N/A /**
325N/A * Customize the wrapper element declaration to be required.
325N/A *
325N/A * <p>
325N/A * If required() is true, then the corresponding generated
325N/A * XML schema element declaration will have <tt>minOccurs="1"</tt>,
325N/A * to indicate that the wrapper element is always expected.
325N/A *
325N/A * <p>
325N/A * Note that this only affects the schema generation, and
325N/A * not the unmarshalling or marshalling capability. This is
325N/A * simply a mechanism to let users express their application constraints
325N/A * better.
325N/A *
325N/A * @since JAXB 2.1
325N/A */
325N/A boolean required() default false;
325N/A}