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