1 /*
2 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.bind.annotation;
27
28 import java.lang.annotation.Retention;
29 import java.lang.annotation.Target;
30
31 import static java.lang.annotation.RetentionPolicy.RUNTIME;
32 import static java.lang.annotation.ElementType.FIELD;
33 import static java.lang.annotation.ElementType.METHOD;
34
35 import org.w3c.dom.Element;
36 import javax.xml.bind.JAXBElement;
37
38 /**
39 * <p>
40 * Annotate a JavaBean multi-valued property to support mixed content.
41 *
42 * <p>
43 * The usage is subject to the following constraints:
44 * <ul>
45 * <li> can be used with @XmlElementRef, @XmlElementRefs or @XmlAnyElement</li>
46 * </ul>
47 * <p>
48 * The following can be inserted into @XmlMixed annotated multi-valued property
49 * <ul>
50 * <li>XML text information items are added as values of java.lang.String.</li>
51 * <li>Children element information items are added as instances of
52 * {@link JAXBElement} or instances with a class that is annotated with
53 * @XmlRootElement.</li>
54 * <li>Unknown content that is not be bound to a JAXB mapped class is inserted
55 * as {@link Element}. (Assumes property annotated with @XmlAnyElement)</li>
56 * </ul>
57 *
58 * Below is an example of binding and creation of mixed content.
59 * <pre>
60 * <!-- schema fragment having mixed content -->
61 * <xs:complexType name="letterBody" mixed="true">
62 * <xs:sequence>
63 * <xs:element name="name" type="xs:string"/>
64 * <xs:element name="quantity" type="xs:positiveInteger"/>
65 * <xs:element name="productName" type="xs:string"/>
66 * <!-- etc. -->
67 * </xs:sequence>
68 * </xs:complexType>
69 * <xs:element name="letterBody" type="letterBody"/>
70 *
71 * // Schema-derived Java code:
72 * // (Only annotations relevant to mixed content are shown below,
73 * // others are ommitted.)
74 * import java.math.BigInteger;
75 * public class ObjectFactory {
76 * // element instance factories
77 * JAXBElement<LetterBody> createLetterBody(LetterBody value);
78 * JAXBElement<String> createLetterBodyName(String value);
79 * JAXBElement<BigInteger> createLetterBodyQuantity(BigInteger value);
80 * JAXBElement<String> createLetterBodyProductName(String value);
81 * // type instance factory
82 * LetterBody> createLetterBody();
83 * }
84 * </pre>
85 * <pre>
86 * public class LetterBody {
87 * // Mixed content can contain instances of Element classes
88 * // Name, Quantity and ProductName. Text data is represented as
89 * // java.util.String for text.
90 * @XmlMixed
91 * @XmlElementRefs({
92 * @XmlElementRef(name="productName", type=JAXBElement.class),
93 * @XmlElementRef(name="quantity", type=JAXBElement.class),
94 * @XmlElementRef(name="name", type=JAXBElement.class)})
95 * List getContent(){...}
96 * }
97 * </pre>
98 * The following is an XML instance document with mixed content
99 * <pre>
100 * <letterBody>
101 * Dear Mr.<name>Robert Smith</name>
102 * Your order of <quantity>1</quantity> <productName>Baby
103 * Monitor</productName> shipped from our warehouse. ....
104 * </letterBody>
105 * </pre>
106 * that can be constructed using following JAXB API calls.
107 * <pre>
108 * LetterBody lb = ObjectFactory.createLetterBody();
109 * JAXBElement<LetterBody> lbe = ObjectFactory.createLetterBody(lb);
110 * List gcl = lb.getContent(); //add mixed content to general content property.
111 * gcl.add("Dear Mr."); // add text information item as a String.
112 *
113 * // add child element information item
114 * gcl.add(ObjectFactory.createLetterBodyName("Robert Smith"));
115 * gcl.add("Your order of "); // add text information item as a String
116 *
117 * // add children element information items
118 * gcl.add(ObjectFactory.
119 * createLetterBodyQuantity(new BigInteger("1")));
120 * gcl.add(ObjectFactory.createLetterBodyProductName("Baby Monitor"));
121 * gcl.add("shipped from our warehouse"); // add text information item
122 * </pre>
123 *
124 * <p>See "Package Specification" in javax.xml.bind.package javadoc for
125 * additional common information.</p>
126 * @author Kohsuke Kawaguchi
127 * @since 1.6, JAXB 2.0
128 */
129 @Retention(RUNTIME)
130 @Target({FIELD,METHOD})
131 public @interface XmlMixed {
132 }