1 /*
2 * Copyright (c) 2004, 2015, 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 {@code @XmlElements} annotation 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 {@code @XmlID}.</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 * {@code
85 *
86 * <!-- XML Representation for a List of {1,2.5}
87 * XML output is not wrapped using another element -->
88 * ...
89 * <A> 1 </A>
90 * <B> 2.5 </B>
91 * ...
92 *
93 * <!-- XML Schema fragment -->
94 * <xs:complexType name="Foo">
95 * <xs:sequence>
96 * <xs:choice minOccurs="0" maxOccurs="unbounded">
97 * <xs:element name="A" type="xs:int"/>
98 * <xs:element name="B" type="xs:float"/>
99 * <xs:choice>
100 * </xs:sequence>
101 * </xs:complexType>
102 *
103 * }</pre>
104 *
105 * <p><b>Example 2:</b> Map to a list of elements wrapped with another element
106 * </p>
107 * <pre>
108 *
109 * // Mapped code fragment
110 * public class Foo {
111 * @XmlElementWrapper(name="bar")
112 * @XmlElements(
113 * @XmlElement(name="A", type=Integer.class),
114 * @XmlElement(name="B", type=Float.class)
115 * }
116 * public List items;
117 * }
118 * {@code
119 *
120 * <!-- XML Schema fragment -->
121 * <xs:complexType name="Foo">
122 * <xs:sequence>
123 * <xs:element name="bar">
124 * <xs:complexType>
125 * <xs:choice minOccurs="0" maxOccurs="unbounded">
126 * <xs:element name="A" type="xs:int"/>
127 * <xs:element name="B" type="xs:float"/>
128 * </xs:choice>
129 * </xs:complexType>
130 * </xs:element>
131 * </xs:sequence>
132 * </xs:complexType>
133 * }</pre>
134 *
135 * <p><b>Example 3:</b> Change element name based on type using an adapter.
136 * </p>
137 * <pre>
138 * class Foo {
139 * @XmlJavaTypeAdapter(QtoPAdapter.class)
140 * @XmlElements({
141 * @XmlElement(name="A",type=PX.class),
142 * @XmlElement(name="B",type=PY.class)
143 * })
144 * Q bar;
145 * }
146 *
147 * @XmlType abstract class P {...}
148 * @XmlType(name="PX") class PX extends P {...}
149 * @XmlType(name="PY") class PY extends P {...}
150 * {@code
151 *
152 * <!-- XML Schema fragment -->
153 * <xs:complexType name="Foo">
154 * <xs:sequence>
155 * <xs:element name="bar">
156 * <xs:complexType>
157 * <xs:choice minOccurs="0" maxOccurs="unbounded">
158 * <xs:element name="A" type="PX"/>
159 * <xs:element name="B" type="PY"/>
160 * </xs:choice>
161 * </xs:complexType>
162 * </xs:element>
163 * </xs:sequence>
164 * </xs:complexType>
165 * }</pre>
166 *
167 * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li></ul>
168 * @see XmlElement
169 * @see XmlElementRef
170 * @see XmlElementRefs
171 * @see XmlJavaTypeAdapter
172 * @since 1.6, JAXB 2.0
173 */
174 @Retention(RUNTIME) @Target({FIELD,METHOD})
175 public @interface XmlElements {
176 /**
177 * Collection of @{@link XmlElement} annotations
178 */
179 XmlElement[] value();
180 }