XmlMixed


1   /*
2    * Copyright 2005 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 java.lang.annotation.Retention  ;
9   import java.lang.annotation.Target  ;
10  
11  import static java.lang.annotation.RetentionPolicy.RUNTIME  ;
12  import static java.lang.annotation.ElementType.FIELD  ;
13  import static java.lang.annotation.ElementType.METHOD  ;
14  
15  import org.w3c.dom.Element  ;
16  import javax.xml.bind.JAXBElement;
17  
18  /**
19   * <p>
20   * Annotate a JavaBean multi-valued property to support mixed content.
21   *
22   * <p>
23   * The usage is subject to the following constraints:
24   * <ul>
25   *   <li> can be used with &#64;XmlElementRef, &#64;XmlElementRefs or &#64;XmlAnyElement</li>
26   * </ul>
27   * <p>
28   * The following can be inserted into &#64;XmlMixed annotated multi-valued property
29   * <ul>
30   * <li>XML text information items are added as values of java.lang.String.</li>
31   * <li>Children element information items are added as instances of
32   * {@link JAXBElement} or instances with a class that is annotated with
33   * &#64;XmlRootElement.</li>
34   * <li>Unknown content that is not be bound to a JAXB mapped class is inserted
35   * as {@link Element}. (Assumes property annotated with &#64;XmlAnyElement)</li>
36   * </ul>
37   *
38   * Below is an example of binding and creation of mixed content.
39   * <pre><xmp>
40   *  <!-- schema fragment having  mixed content -->
41   *  <xs:complexType name="letterBody" mixed="true">
42   *    <xs:sequence>
43   *  <xs:element name="name" type="xs:string"/>
44   *  <xs:element name="quantity" type="xs:positiveInteger"/>
45   *  <xs:element name="productName" type="xs:string"/>
46   *  <!-- etc. -->
47   *    </xs:sequence>
48   *  </xs:complexType>
49   *  <xs:element name="letterBody" type="letterBody"/>
50   * 
51   * // Schema-derived Java code: 
52   * // (Only annotations relevant to mixed content are shown below, 
53   * //  others are ommitted.)
54   * import java.math.BigInteger;
55   * public class ObjectFactory {
56   *  // element instance factories
57   *  JAXBElement<LetterBody> createLetterBody(LetterBody value);
58   *  JAXBElement<String>     createLetterBodyName(String value);
59   *  JAXBElement<BigInteger> createLetterBodyQuantity(BigInteger value);
60   *  JAXBElement<String>     createLetterBodyProductName(String value);
61   *      // type instance factory
62   *  LetterBody> createLetterBody();
63   * }
64   * </xmp></pre>
65   * <pre>
66   * public class LetterBody {
67   *  // Mixed content can contain instances of Element classes
68   *  // Name, Quantity and ProductName. Text data is represented as
69   *  // java.util.String for text.
70   *  &#64;XmlMixed 
71   *  &#64;XmlElementRefs({
72   *      &#64;XmlElementRef(name="productName", type=JAXBElement.class),
73   *      &#64;XmlElementRef(name="quantity", type=JAXBElement.class),
74   *      &#64;XmlElementRef(name="name", type=JAXBElement.class)})
75   *  List getContent(){...}
76   * }
77   * </pre>
78   * The following is an XML instance document with mixed content
79   * <pre><xmp>
80   * <letterBody>
81   * Dear Mr.<name>Robert Smith</name>
82   * Your order of <quantity>1</quantity> <productName>Baby
83   * Monitor</productName> shipped from our warehouse. ....
84   * </letterBody>
85   * </xmp></pre>
86   * that can be constructed using following JAXB API calls.
87   * <pre><xmp>
88   * LetterBody lb = ObjectFactory.createLetterBody();
89   * JAXBElement<LetterBody> lbe = ObjectFactory.createLetterBody(lb);
90   * List gcl = lb.getContent();  //add mixed content to general content property.
91   * gcl.add("Dear Mr.");  // add text information item as a String.
92   * 
93   * // add child element information item
94   * gcl.add(ObjectFactory.createLetterBodyName("Robert Smith"));
95   * gcl.add("Your order of "); // add text information item as a String
96   * 
97   * // add children element information items
98   * gcl.add(ObjectFactory.
99   *          createLetterBodyQuantity(new BigInteger("1")));
100  * gcl.add(ObjectFactory.createLetterBodyProductName("Baby Monitor"));
101  * gcl.add("shipped from our warehouse");  // add text information item
102  * </xmp></pre>
103  *
104  * <p>See "Package Specification" in javax.xml.bind.package javadoc for
105  * additional common information.</p>
106  * @author Kohsuke Kawaguchi
107  * @since JAXB2.0
108  */
109 @Retention  (RUNTIME)
110 @Target  ({FIELD,METHOD})
111 public @interface XmlMixed {
112 }
113
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags