View Javadoc
1   /*
2    * Copyright (c) 2005, 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 java.lang.annotation.Retention;
29  import java.lang.annotation.Target;
30  import static java.lang.annotation.RetentionPolicy.RUNTIME;
31  import static java.lang.annotation.ElementType.FIELD;
32  import static java.lang.annotation.ElementType.METHOD;
33  import static java.lang.annotation.ElementType.PARAMETER;
34  
35  /**
36   * Used to map a property to a list simple type.
37   *
38   * <p><b>Usage</b> </p>
39   * <p>
40   * The <tt>@XmlList</tt> annotation can be used with the
41   * following program elements:
42   * <ul>
43   *   <li> JavaBean property </li>
44   *   <li> field </li>
45   * </ul>
46   *
47   * <p>
48   * When a collection property is annotated just with @XmlElement,
49   * each item in the collection will be wrapped by an element.
50   * For example,
51   *
52   * <pre>
53   * &#64;XmlRootElement
54   * class Foo {
55   *     &#64;XmlElement
56   *     List&lt;String> data;
57   * }
58   * </pre>
59   *
60   * would produce XML like this:
61   *
62   * <pre>
63   * &lt;foo>
64   *   &lt;data>abc</data>
65   *   &lt;data>def</data>
66   * &lt;/foo>
67   * </pre>
68   *
69   * &#64;XmlList annotation, on the other hand, allows multiple values to be
70   * represented as whitespace-separated tokens in a single element. For example,
71   *
72   * <pre>
73   * &#64;XmlRootElement
74   * class Foo {
75   *     &#64;XmlElement
76   *     &#64;XmlList
77   *     List&lt;String> data;
78   * }
79   * </pre>
80   *
81   * the above code will produce XML like this:
82   *
83   * <pre>
84   * &lt;foo>
85   *   &lt;data>abc def</data>
86   * &lt;/foo>
87   * </pre>
88   *
89   * <p>This annotation can be used with the following annotations:
90   *        {@link XmlElement},
91   *        {@link XmlAttribute},
92   *        {@link XmlValue},
93   *        {@link XmlIDREF}.
94   *  <ul>
95   *    <li> The use of <tt>@XmlList</tt> with {@link XmlValue} while
96   *         allowed, is redundant since  {@link XmlList} maps a
97   *         collection type to a simple schema type that derives by
98   *         list just as {@link XmlValue} would. </li>
99   *
100  *    <li> The use of <tt>@XmlList</tt> with {@link XmlAttribute} while
101  *         allowed, is redundant since  {@link XmlList} maps a
102  *         collection type to a simple schema type that derives by
103  *         list just as {@link XmlAttribute} would. </li>
104  *  </ul>
105  *
106  * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li></ul>
107  * @since JAXB2.0
108  */
109 @Retention(RUNTIME) @Target({FIELD,METHOD,PARAMETER})
110 public @interface XmlList {
111 }