001: package javax.xml.bind.annotation;
002:
003: import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
004: import static java.lang.annotation.RetentionPolicy.RUNTIME;
005: import static java.lang.annotation.ElementType.FIELD;
006: import static java.lang.annotation.ElementType.METHOD;
007: import java.lang.annotation.Retention;
008: import java.lang.annotation.Target;
009:
010: /**
011: * Generates a wrapper element around XML representation.
012: *
013: * This is primarily intended to be used to produce a wrapper
014: * XML element around collections. The annotation therefore supports
015: * two forms of serialization shown below.
016: *
017: * <pre>
018: * //Example: code fragment
019: * int[] names;
020: *
021: * // XML Serialization Form 1 (Unwrapped collection)
022: * <names> ... </names>
023: * <names> ... </names>
024: *
025: * // XML Serialization Form 2 ( Wrapped collection )
026: * <wrapperElement>
027: * <names> value-of-item </names>
028: * <names> value-of-item </names>
029: * ....
030: * </wrapperElement>
031: * </pre>
032: *
033: * <p> The two serialized XML forms allow a null collection to be
034: * represented either by absence or presence of an element with a
035: * nillable attribute.
036: *
037: * <p> <b>Usage</b> </p>
038: * <p>
039: * The <tt>@XmlElementWrapper</tt> annotation can be used with the
040: * following program elements:
041: * <ul>
042: * <li> JavaBean property </li>
043: * <li> non static, non transient field </li>
044: * </ul>
045: *
046: * <p>The usage is subject to the following constraints:
047: * <ul>
048: * <li> The property must be a collection property </li>
049: * <li> This annotation can be used with the following annotations:
050: * {@link XmlElement},
051: * {@link XmlElements},
052: * {@link XmlElementRef},
053: * {@link XmlElementRefs},
054: * {@link XmlJavaTypeAdapter}</li>.
055: * </ul>
056: *
057: * <p>See "Package Specification" in javax.xml.bind.package javadoc for
058: * additional common information.</p>
059: *
060: * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li></ul>
061: * @see XmlElement
062: * @see XmlElements
063: * @see XmlElementRef
064: * @see XmlElementRefs
065: * @since JAXB2.0
066: *
067: */
068:
069: @Retention(RUNTIME)
070: @Target({FIELD,METHOD})
071: public @interface XmlElementWrapper {
072: /**
073: * Name of the XML wrapper element. By default, the XML wrapper
074: * element name is derived from the JavaBean property name.
075: */
076: String name() default "##default";
077:
078: /**
079: * XML target namespace of the XML wrapper element.
080: * <p>
081: * If the value is "##default", then the namespace is determined
082: * as follows:
083: * <ol>
084: * <li>
085: * If the enclosing package has {@link XmlSchema} annotation,
086: * and its {@link XmlSchema#elementFormDefault() elementFormDefault}
087: * is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of
088: * the enclosing class.
089: *
090: * <li>
091: * Otherwise "" (which produces unqualified element in the default
092: * namespace.
093: * </ol>
094: */
095: String namespace() default "##default";
096:
097: /**
098: * If true, the absence of the collection is represented by
099: * using <tt>xsi:nil='true'</tt>. Otherwise, it is represented by
100: * the absence of the element.
101: */
102: boolean nillable() default false;
103:
104: /**
105: * Customize the wrapper element declaration to be required.
106: *
107: * <p>
108: * If required() is true, then the corresponding generated
109: * XML schema element declaration will have <tt>minOccurs="1"</tt>,
110: * to indicate that the wrapper element is always expected.
111: *
112: * <p>
113: * Note that this only affects the schema generation, and
114: * not the unmarshalling or marshalling capability. This is
115: * simply a mechanism to let users express their application constraints
116: * better.
117: *
118: * @since JAXB 2.1
119: */
120: boolean required() default false;
121: }
|