1 /*
2 * Copyright (c) 2004, 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 */
25
26 package javax.xml.bind.annotation;
27
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;
34
35 /**
36 * <p>
37 * A container for multiple @{@link XmlElement} annotations.
38 *
39 * Multiple annotations of the same type are not allowed on a program
40 * element. This annotation therefore serves as a container annotation
41 * for multiple @XmlElements as follows:
42 *
43 * <pre>
44 * @XmlElements({ @XmlElement(...),@XmlElement(...) })
45 * </pre>
46 *
47 * <p>The <tt>@XmlElements</tt> annnotation can be used with the
48 * following program elements: </p>
49 * <ul>
50 * <li> a JavaBean property </li>
51 * <li> non static, non transient field </li>
52 * </ul>
53 *
54 * This annotation is intended for annotation a JavaBean collection
55 * property (e.g. List).
56 *
57 * <p><b>Usage</b></p>
58 *
59 * <p>The usage is subject to the following constraints:
60 * <ul>
61 * <li> This annotation can be used with the following
62 * annotations: @{@link XmlIDREF}, @{@link XmlElementWrapper}. </li>
63 * <li> If @XmlIDREF is also specified on the JavaBean property,
64 * then each @XmlElement.type() must contain a JavaBean
65 * property annotated with <tt>@XmlID</tt>.</li>
66 * </ul>
67 *
68 * <p>See "Package Specification" in javax.xml.bind.package javadoc for
69 * additional common information.</p>
70 *
71 * <hr>
72 *
73 * <p><b>Example 1:</b> Map to a list of elements</p>
74 * <pre>
75 *
76 * // Mapped code fragment
77 * public class Foo {
78 * @XmlElements(
79 * @XmlElement(name="A", type=Integer.class),
80 * @XmlElement(name="B", type=Float.class)
81 * }
82 * public List items;
83 * }
84 *
85 * <!-- XML Representation for a List of {1,2.5}
86 * XML output is not wrapped using another element -->
87 * ...
88 * <A> 1 </A>
89 * <B> 2.5 </B>
90 * ...
91 *
92 * <!-- XML Schema fragment -->
93 * <xs:complexType name="Foo">
94 * <xs:sequence>
95 * <xs:choice minOccurs="0" maxOccurs="unbounded">
96 * <xs:element name="A" type="xs:int"/>
97 * <xs:element name="B" type="xs:float"/>
98 * <xs:choice>
99 * </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 1.6, JAXB 2.0
170 */
171 @Retention(RUNTIME) @Target({FIELD,METHOD})
172 public @interface XmlElements {
173 /**
174 * Collection of @{@link XmlElement} annotations
175 */
176 XmlElement[] value();
177 }