XmlElements


1   /*
2    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
3    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4    */
5   
6   package javax.xml.bind.annotation;
7   
8   import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
9   import static java.lang.annotation.RetentionPolicy.RUNTIME  ;
10  import static java.lang.annotation.ElementType.FIELD  ;
11  import static java.lang.annotation.ElementType.METHOD  ;
12  import java.lang.annotation.Retention  ;
13  import java.lang.annotation.Target  ;
14  
15  /**
16   * <p>
17   * A container for multiple @{@link XmlElement} annotations.
18   *
19   * Multiple annotations of the same type are not allowed on a program
20   * element. This annotation therefore serves as a container annotation
21   * for multiple &#64;XmlElements as follows:
22   *
23   * <pre>
24   * &#64;XmlElements({ @XmlElement(...),@XmlElement(...) })
25   * </pre>
26   *
27   * <p>The <tt>@XmlElements</tt> annnotation can be used with the
28   * following program elements: </p>
29   * <ul>
30   *   <li> a JavaBean property </li>
31   *   <li> non static, non transient field </li>
32   * </ul>
33   *
34   * This annotation is intended for annotation a JavaBean collection
35   * property (e.g. List). 
36   *
37   * <p><b>Usage</b></p>
38   *
39   * <p>The usage is subject to the following constraints:
40   * <ul>
41   *   <li> This annotation can be used with the following
42   *        annotations: @{@link XmlIDREF}, @{@link XmlElementWrapper}. </li>
43   *   <li> If @XmlIDREF is also specified on the JavaBean property,
44   *        then each &#64;XmlElement.type() must contain a JavaBean
45   *        property annotated with <tt>&#64;XmlID</tt>.</li>
46   * </ul>
47   *
48   * <p>See "Package Specification" in javax.xml.bind.package javadoc for
49   * additional common information.</p>
50   *
51   * <hr>
52   * 
53   * <p><b>Example 1:</b> Map to a list of elements</p>
54   * <pre>
55   *    
56   *    // Mapped code fragment
57   *    public class Foo {
58   *        &#64;XmlElements(
59   *            &#64;XmlElement(name="A", type=Integer.class),
60   *            &#64;XmlElement(name="B", type=Float.class)
61   *         }
62   *         public List items;
63   *    }
64   *
65   *    &lt;!-- XML Representation for a List of {1,2.5} 
66   *            XML output is not wrapped using another element -->
67   *    ...
68   *    <A> 1 </A>
69   *    <B> 2.5 </B>
70   *    ...
71   *
72   *    &lt;!-- XML Schema fragment -->
73   *    &lt;xs:complexType name="Foo">
74   *      &lt;xs:sequence>
75   *        &lt;xs:choice minOccurs="0" maxOccurs="unbounded">
76   *          &lt;xs:element name="A" type="xs:int"/>
77   *          &lt;xs:element name="B" type="xs:float"/>
78   *        &lt;xs:choice>
79   *      &lt;/xs:sequence>
80   *    &lt;/xs:complexType>
81   *
82   * </pre>
83   *
84   * <p><b>Example 2:</b> Map to a list of elements wrapped with another element
85   * </p>
86   * <pre>
87   * 
88   *    // Mapped code fragment
89   *    public class Foo {
90   *        &#64;XmlElementWrapper(name="bar")
91   *        &#64;XmlElements(
92   *            &#64;XmlElement(name="A", type=Integer.class),
93   *            &#64;XmlElement(name="B", type=Float.class)
94   *        }
95   *        public List items;
96   *    }
97   *
98   *    &lt;!-- XML Schema fragment -->
99   *    &lt;xs:complexType name="Foo">
100  *      &lt;xs:sequence>
101  *        &lt;xs:element name="bar">
102  *          &lt;xs:complexType>
103  *            &lt;xs:choice minOccurs="0" maxOccurs="unbounded">
104  *              &lt;xs:element name="A" type="xs:int"/>
105  *              &lt;xs:element name="B" type="xs:float"/>
106  *            &lt;/xs:choice>
107  *          &lt;/xs:complexType>
108  *        &lt;/xs:element>
109  *      &lt;/xs:sequence>
110  *    &lt;/xs:complexType>
111  * </pre>
112  *
113  * <p><b>Example 3:</b> Change element name based on type using an adapter. 
114  * </p>
115  * <pre>
116  *    class Foo {
117  *       &#64;XmlJavaTypeAdapter(QtoPAdapter.class)
118  *       &#64;XmlElements({
119  *           &#64;XmlElement(name="A",type=PX.class),
120  *           &#64;XmlElement(name="B",type=PY.class)
121  *       })
122  *       Q bar;
123  *    }
124  * 
125  *    &#64;XmlType abstract class P {...}
126  *    &#64;XmlType(name="PX") class PX extends P {...}
127  *    &#64;XmlType(name="PY") class PY extends P {...}
128  *
129  *    &lt;!-- XML Schema fragment -->
130  *    &lt;xs:complexType name="Foo">
131  *      &lt;xs:sequence>
132  *        &lt;xs:element name="bar">
133  *          &lt;xs:complexType>
134  *            &lt;xs:choice minOccurs="0" maxOccurs="unbounded">
135  *              &lt;xs:element name="A" type="PX"/>
136  *              &lt;xs:element name="B" type="PY"/>
137  *            &lt;/xs:choice>
138  *          &lt;/xs:complexType>
139  *        &lt;/xs:element>
140  *      &lt;/xs:sequence>
141  *    &lt;/xs:complexType>
142  * </pre>
143  * 
144  * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li></ul>
145  * @see XmlElement 
146  * @see XmlElementRef
147  * @see XmlElementRefs
148  * @see XmlJavaTypeAdapter
149  * @since JAXB2.0
150  */
151 @Retention  (RUNTIME) @Target  ({FIELD,METHOD})
152 public @interface XmlElements {
153     /**
154      * Collection of @{@link XmlElement} annotations
155      */
156     XmlElement[] value();
157 }
158
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags