XmlElementWrapper


1   package javax.xml.bind.annotation;
2   
3   import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
4   import static java.lang.annotation.RetentionPolicy.RUNTIME  ;
5   import static java.lang.annotation.ElementType.FIELD  ;
6   import static java.lang.annotation.ElementType.METHOD  ;
7   import java.lang.annotation.Retention  ;
8   import java.lang.annotation.Target  ;
9   
10  /**
11   * Generates a wrapper element around XML representation.
12   *
13   * This is primarily intended to be used to produce a wrapper
14   * XML element around collections. The annotation therefore supports
15   * two forms of serialization shown below. 
16   *
17   * <pre>
18   *    //Example: code fragment
19   *      int[] names;
20   *
21   *    // XML Serialization Form 1 (Unwrapped collection)
22   *    &lt;names> ... &lt;/names>
23   *    &lt;names> ... &lt;/names>
24   * 
25   *    // XML Serialization Form 2 ( Wrapped collection )
26   *    &lt;wrapperElement>
27   *       &lt;names> value-of-item &lt;/names>
28   *       &lt;names> value-of-item &lt;/names>
29   *       ....
30   *    &lt;/wrapperElement>
31   * </pre>
32   *
33   * <p> The two serialized XML forms allow a null collection to be
34   * represented either by absence or presence of an element with a
35   * nillable attribute.
36   * 
37   * <p> <b>Usage</b> </p>
38   * <p>
39   * The <tt>@XmlElementWrapper</tt> annotation can be used with the
40   * following program elements: 
41   * <ul> 
42   *   <li> JavaBean property </li>
43   *   <li> non static, non transient field </li>
44   * </ul>
45   *
46   * <p>The usage is subject to the following constraints:
47   * <ul>
48   *   <li> The property must be a collection property </li>
49   *   <li> This annotation can be used with the following annotations:
50   *            {@link XmlElement}, 
51   *            {@link XmlElements},
52   *            {@link XmlElementRef},
53   *            {@link XmlElementRefs},
54   *            {@link XmlJavaTypeAdapter}</li>.
55   * </ul>
56   *
57   * <p>See "Package Specification" in javax.xml.bind.package javadoc for
58   * additional common information.</p>
59   *
60   * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li></ul>
61   * @see XmlElement 
62   * @see XmlElements
63   * @see XmlElementRef
64   * @see XmlElementRefs
65   * @since JAXB2.0
66   *
67   */
68  
69  @Retention  (RUNTIME) @Target  ({FIELD, METHOD})
70  public @interface XmlElementWrapper {
71      /**
72       * Name of the XML wrapper element. By default, the XML wrapper
73       * element name is derived from the JavaBean property name.
74       */
75      String   name() default "##default";
76  
77      /**
78       * XML target namespace of the XML wrapper element.
79       * <p>
80       * If the value is "##default", then the namespace is determined
81       * as follows:
82       * <ol>
83       *  <li>
84       *  If the enclosing package has {@link XmlSchema} annotation,
85       *  and its {@link XmlSchema#elementFormDefault() elementFormDefault}
86       *  is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of
87       *  the enclosing class.
88       *
89       *  <li>
90       *  Otherwise "" (which produces unqualified element in the default
91       *  namespace.
92       * </ol>
93       */
94      String   namespace() default "##default";
95  
96      /**
97       * If true, the absence of the collection is represented by
98       * using <tt>xsi:nil='true'</tt>. Otherwise, it is represented by
99       * the absence of the element.
100      */
101     boolean nillable() default false;
102 
103     /**
104      * Customize the wrapper element declaration to be required.
105      *
106      * <p>
107      * If required() is true, then the corresponding generated
108      * XML schema element declaration will have <tt>minOccurs="1"</tt>,
109      * to indicate that the wrapper element is always expected.
110      *
111      * <p>
112      * Note that this only affects the schema generation, and
113      * not the unmarshalling or marshalling capability. This is
114      * simply a mechanism to let users express their application constraints
115      * better.
116      *
117      * @since JAXB 2.1
118      */
119     boolean required() default false;
120 }
121
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags