001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.bind.annotation;
027
028 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
029 import static java.lang.annotation.RetentionPolicy.RUNTIME;
030 import static java.lang.annotation.ElementType.FIELD;
031 import static java.lang.annotation.ElementType.METHOD;
032 import java.lang.annotation.Retention;
033 import java.lang.annotation.Target;
034
035 /**
036 * Generates a wrapper element around XML representation.
037 *
038 * This is primarily intended to be used to produce a wrapper
039 * XML element around collections. The annotation therefore supports
040 * two forms of serialization shown below.
041 *
042 * <pre>
043 * //Example: code fragment
044 * int[] names;
045 *
046 * // XML Serialization Form 1 (Unwrapped collection)
047 * <names> ... </names>
048 * <names> ... </names>
049 *
050 * // XML Serialization Form 2 ( Wrapped collection )
051 * <wrapperElement>
052 * <names> value-of-item </names>
053 * <names> value-of-item </names>
054 * ....
055 * </wrapperElement>
056 * </pre>
057 *
058 * <p> The two serialized XML forms allow a null collection to be
059 * represented either by absence or presence of an element with a
060 * nillable attribute.
061 *
062 * <p> <b>Usage</b> </p>
063 * <p>
064 * The <tt>@XmlElementWrapper</tt> annotation can be used with the
065 * following program elements:
066 * <ul>
067 * <li> JavaBean property </li>
068 * <li> non static, non transient field </li>
069 * </ul>
070 *
071 * <p>The usage is subject to the following constraints:
072 * <ul>
073 * <li> The property must be a collection property </li>
074 * <li> This annotation can be used with the following annotations:
075 * {@link XmlElement},
076 * {@link XmlElements},
077 * {@link XmlElementRef},
078 * {@link XmlElementRefs},
079 * {@link XmlJavaTypeAdapter}</li>.
080 * </ul>
081 *
082 * <p>See "Package Specification" in javax.xml.bind.package javadoc for
083 * additional common information.</p>
084 *
085 * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li></ul>
086 * @see XmlElement
087 * @see XmlElements
088 * @see XmlElementRef
089 * @see XmlElementRefs
090 * @since JAXB2.0
091 *
092 */
093
094 @Retention(RUNTIME)
095 @Target({FIELD,METHOD})
096 public @interface XmlElementWrapper {
097 /**
098 * Name of the XML wrapper element. By default, the XML wrapper
099 * element name is derived from the JavaBean property name.
100 */
101 String name() default "##default";
102
103 /**
104 * XML target namespace of the XML wrapper element.
105 * <p>
106 * If the value is "##default", then the namespace is determined
107 * as follows:
108 * <ol>
109 * <li>
110 * If the enclosing package has {@link XmlSchema} annotation,
111 * and its {@link XmlSchema#elementFormDefault() elementFormDefault}
112 * is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of
113 * the enclosing class.
114 *
115 * <li>
116 * Otherwise "" (which produces unqualified element in the default
117 * namespace.
118 * </ol>
119 */
120 String namespace() default "##default";
121
122 /**
123 * If true, the absence of the collection is represented by
124 * using <tt>xsi:nil='true'</tt>. Otherwise, it is represented by
125 * the absence of the element.
126 */
127 boolean nillable() default false;
128 }
|