001: /*
002: * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.bind.annotation;
007:
008: import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
009: import static java.lang.annotation.RetentionPolicy.RUNTIME;
010: import static java.lang.annotation.ElementType.FIELD;
011: import static java.lang.annotation.ElementType.METHOD;
012: import java.lang.annotation.Retention;
013: import java.lang.annotation.Target;
014:
015: /**
016: * <p>
017: * A container for multiple @{@link XmlElement} annotations.
018: *
019: * Multiple annotations of the same type are not allowed on a program
020: * element. This annotation therefore serves as a container annotation
021: * for multiple @XmlElements as follows:
022: *
023: * <pre>
024: * @XmlElements({ @XmlElement(...),@XmlElement(...) })
025: * </pre>
026: *
027: * <p>The <tt>@XmlElements</tt> annnotation can be used with the
028: * following program elements: </p>
029: * <ul>
030: * <li> a JavaBean property </li>
031: * <li> non static, non transient field </li>
032: * </ul>
033: *
034: * This annotation is intended for annotation a JavaBean collection
035: * property (e.g. List).
036: *
037: * <p><b>Usage</b></p>
038: *
039: * <p>The usage is subject to the following constraints:
040: * <ul>
041: * <li> This annotation can be used with the following
042: * annotations: @{@link XmlIDREF}, @{@link XmlElementWrapper}. </li>
043: * <li> If @XmlIDREF is also specified on the JavaBean property,
044: * then each @XmlElement.type() must contain a JavaBean
045: * property annotated with <tt>@XmlID</tt>.</li>
046: * </ul>
047: *
048: * <p>See "Package Specification" in javax.xml.bind.package javadoc for
049: * additional common information.</p>
050: *
051: * <hr>
052: *
053: * <p><b>Example 1:</b> Map to a list of elements</p>
054: * <pre>
055: *
056: * // Mapped code fragment
057: * public class Foo {
058: * @XmlElements(
059: * @XmlElement(name="A", type=Integer.class),
060: * @XmlElement(name="B", type=Float.class)
061: * }
062: * public List items;
063: * }
064: *
065: * <!-- XML Representation for a List of {1,2.5}
066: * XML output is not wrapped using another element -->
067: * ...
068: * <A> 1 </A>
069: * <B> 2.5 </B>
070: * ...
071: *
072: * <!-- XML Schema fragment -->
073: * <xs:complexType name="Foo">
074: * <xs:sequence>
075: * <xs:choice minOccurs="0" maxOccurs="unbounded">
076: * <xs:element name="A" type="xs:int"/>
077: * <xs:element name="B" type="xs:float"/>
078: * <xs:choice>
079: * </xs:sequence>
080: * </xs:complexType>
081: *
082: * </pre>
083: *
084: * <p><b>Example 2:</b> Map to a list of elements wrapped with another element
085: * </p>
086: * <pre>
087: *
088: * // Mapped code fragment
089: * public class Foo {
090: * @XmlElementWrapper(name="bar")
091: * @XmlElements(
092: * @XmlElement(name="A", type=Integer.class),
093: * @XmlElement(name="B", type=Float.class)
094: * }
095: * public List items;
096: * }
097: *
098: * <!-- XML Schema fragment -->
099: * <xs:complexType name="Foo">
100: * <xs:sequence>
101: * <xs:element name="bar">
102: * <xs:complexType>
103: * <xs:choice minOccurs="0" maxOccurs="unbounded">
104: * <xs:element name="A" type="xs:int"/>
105: * <xs:element name="B" type="xs:float"/>
106: * </xs:choice>
107: * </xs:complexType>
108: * </xs:element>
109: * </xs:sequence>
110: * </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: * @XmlJavaTypeAdapter(QtoPAdapter.class)
118: * @XmlElements({
119: * @XmlElement(name="A",type=PX.class),
120: * @XmlElement(name="B",type=PY.class)
121: * })
122: * Q bar;
123: * }
124: *
125: * @XmlType abstract class P {...}
126: * @XmlType(name="PX") class PX extends P {...}
127: * @XmlType(name="PY") class PY extends P {...}
128: *
129: * <!-- XML Schema fragment -->
130: * <xs:complexType name="Foo">
131: * <xs:sequence>
132: * <xs:element name="bar">
133: * <xs:complexType>
134: * <xs:choice minOccurs="0" maxOccurs="unbounded">
135: * <xs:element name="A" type="PX"/>
136: * <xs:element name="B" type="PY"/>
137: * </xs:choice>
138: * </xs:complexType>
139: * </xs:element>
140: * </xs:sequence>
141: * </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)
152: @Target({FIELD,METHOD})
153: public @interface XmlElements {
154: /**
155: * Collection of @{@link XmlElement} annotations
156: */
157: XmlElement[] value();
158: }
|