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 JAXB2.0 128 */ 129 @Retention(RUNTIME) 130 @Target({FIELD,METHOD}) 131 public @interface XmlMixed { 132 }