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 * <p>
037 * A container for multiple @{@link XmlElement} annotations.
038 *
039 * Multiple annotations of the same type are not allowed on a program
040 * element. This annotation therefore serves as a container annotation
041 * for multiple @XmlElements as follows:
042 *
043 * <pre>
044 * @XmlElements({ @XmlElement(...),@XmlElement(...) })
045 * </pre>
046 *
047 * <p>The <tt>@XmlElements</tt> annnotation can be used with the
048 * following program elements: </p>
049 * <ul>
050 * <li> a JavaBean property </li>
051 * <li> non static, non transient field </li>
052 * </ul>
053 *
054 * This annotation is intended for annotation a JavaBean collection
055 * property (e.g. List).
056 *
057 * <p><b>Usage</b></p>
058 *
059 * <p>The usage is subject to the following constraints:
060 * <ul>
061 * <li> This annotation can be used with the following
062 * annotations: @{@link XmlIDREF}, @{@link XmlElementWrapper}. </li>
063 * <li> If @XmlIDREF is also specified on the JavaBean property,
064 * then each @XmlElement.type() must contain a JavaBean
065 * property annotated with <tt>@XmlID</tt>.</li>
066 * </ul>
067 *
068 * <p>See "Package Specification" in javax.xml.bind.package javadoc for
069 * additional common information.</p>
070 *
071 * <hr>
072 *
073 * <p><b>Example 1:</b> Map to a list of elements</p>
074 * <pre>
075 *
076 * // Mapped code fragment
077 * public class Foo {
078 * @XmlElements(
079 * @XmlElement(name="A", type=Integer.class),
080 * @XmlElement(name="B", type=Float.class)
081 * }
082 * public List items;
083 * }
084 *
085 * <!-- XML Representation for a List of {1,2.5}
086 * XML output is not wrapped using another element -->
087 * ...
088 * <A> 1 </A>
089 * <B> 2.5 </B>
090 * ...
091 *
092 * <!-- XML Schema fragment -->
093 * <xs:complexType name="Foo">
094 * <xs:sequence>
095 * <xs:choice minOccurs="0" maxOccurs="unbounded">
096 * <xs:element name="A" type="xs:int"/>
097 * <xs:element name="B" type="xs:float"/>
098 * <xs:choice>
099 * </xs:sequence>
100 * </xs:complexType>
101 *
102 * </pre>
103 *
104 * <p><b>Example 2:</b> Map to a list of elements wrapped with another element
105 * </p>
106 * <pre>
107 *
108 * // Mapped code fragment
109 * public class Foo {
110 * @XmlElementWrapper(name="bar")
111 * @XmlElements(
112 * @XmlElement(name="A", type=Integer.class),
113 * @XmlElement(name="B", type=Float.class)
114 * }
115 * public List items;
116 * }
117 *
118 * <!-- XML Schema fragment -->
119 * <xs:complexType name="Foo">
120 * <xs:sequence>
121 * <xs:element name="bar">
122 * <xs:complexType>
123 * <xs:choice minOccurs="0" maxOccurs="unbounded">
124 * <xs:element name="A" type="xs:int"/>
125 * <xs:element name="B" type="xs:float"/>
126 * </xs:choice>
127 * </xs:complexType>
128 * </xs:element>
129 * </xs:sequence>
130 * </xs:complexType>
131 * </pre>
132 *
133 * <p><b>Example 3:</b> Change element name based on type using an adapter.
134 * </p>
135 * <pre>
136 * class Foo {
137 * @XmlJavaTypeAdapter(QtoPAdapter.class)
138 * @XmlElements({
139 * @XmlElement(name="A",type=PX.class),
140 * @XmlElement(name="B",type=PY.class)
141 * })
142 * Q bar;
143 * }
144 *
145 * @XmlType abstract class P {...}
146 * @XmlType(name="PX") class PX extends P {...}
147 * @XmlType(name="PY") class PY extends P {...}
148 *
149 * <!-- XML Schema fragment -->
150 * <xs:complexType name="Foo">
151 * <xs:sequence>
152 * <xs:element name="bar">
153 * <xs:complexType>
154 * <xs:choice minOccurs="0" maxOccurs="unbounded">
155 * <xs:element name="A" type="PX"/>
156 * <xs:element name="B" type="PY"/>
157 * </xs:choice>
158 * </xs:complexType>
159 * </xs:element>
160 * </xs:sequence>
161 * </xs:complexType>
162 * </pre>
163 *
164 * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li></ul>
165 * @see XmlElement
166 * @see XmlElementRef
167 * @see XmlElementRefs
168 * @see XmlJavaTypeAdapter
169 * @since JAXB2.0
170 */
171 @Retention(RUNTIME)
172 @Target({FIELD,METHOD})
173 public @interface XmlElements {
174 /**
175 * Collection of @{@link XmlElement} annotations
176 */
177 XmlElement[] value();
178 }
|