Source Code Cross Referenced for XmlMixed.java in  » 6.0-JDK-Modules » jaxb-api » javax » xml » bind » annotation » Java Source Code / Java DocumentationJava Source Code and Java Documentation

001:        /*
002:         * Copyright 2005 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 java.lang.annotation.Retention;
009:        import java.lang.annotation.Target;
010:
011:        import static java.lang.annotation.RetentionPolicy.RUNTIME;
012:        import static java.lang.annotation.ElementType.FIELD;
013:        import static java.lang.annotation.ElementType.METHOD;
014:
015:        import org.w3c.dom.Element;
016:        import javax.xml.bind.JAXBElement;
017:
018:        /**
019:         * <p>
020:         * Annotate a JavaBean multi-valued property to support mixed content.
021:         *
022:         * <p>
023:         * The usage is subject to the following constraints:
024:         * <ul>
025:         *   <li> can be used with &#64;XmlElementRef, &#64;XmlElementRefs or &#64;XmlAnyElement</li>
026:         * </ul>
027:         * <p>
028:         * The following can be inserted into &#64;XmlMixed annotated multi-valued property
029:         * <ul>
030:         * <li>XML text information items are added as values of java.lang.String.</li>
031:         * <li>Children element information items are added as instances of
032:         * {@link JAXBElement} or instances with a class that is annotated with
033:         * &#64;XmlRootElement.</li>
034:         * <li>Unknown content that is not be bound to a JAXB mapped class is inserted
035:         * as {@link Element}. (Assumes property annotated with &#64;XmlAnyElement)</li>
036:         * </ul>
037:         *
038:         * Below is an example of binding and creation of mixed content.
039:         * <pre><xmp>
040:         *  <!-- schema fragment having  mixed content -->
041:         *  <xs:complexType name="letterBody" mixed="true">
042:         *    <xs:sequence>
043:         *	<xs:element name="name" type="xs:string"/>
044:         *	<xs:element name="quantity" type="xs:positiveInteger"/>
045:         *	<xs:element name="productName" type="xs:string"/>
046:         *	<!-- etc. -->
047:         *    </xs:sequence>
048:         *  </xs:complexType>
049:         *  <xs:element name="letterBody" type="letterBody"/>
050:         * 
051:         * // Schema-derived Java code: 
052:         * // (Only annotations relevant to mixed content are shown below, 
053:         * //  others are ommitted.)
054:         * import java.math.BigInteger;
055:         * public class ObjectFactory {
056:         * 	// element instance factories
057:         * 	JAXBElement<LetterBody> createLetterBody(LetterBody value);
058:         * 	JAXBElement<String>     createLetterBodyName(String value);
059:         * 	JAXBElement<BigInteger> createLetterBodyQuantity(BigInteger value);
060:         * 	JAXBElement<String>     createLetterBodyProductName(String value);
061:         *      // type instance factory
062:         * 	LetterBody> createLetterBody();
063:         * }
064:         * </xmp></pre>
065:         * <pre>
066:         * public class LetterBody {
067:         * 	// Mixed content can contain instances of Element classes
068:         * 	// Name, Quantity and ProductName. Text data is represented as
069:         *	// java.util.String for text.
070:         *	&#64;XmlMixed 
071:         * 	&#64;XmlElementRefs({
072:         *		&#64;XmlElementRef(name="productName", type=JAXBElement.class),
073:         *		&#64;XmlElementRef(name="quantity", type=JAXBElement.class),
074:         *		&#64;XmlElementRef(name="name", type=JAXBElement.class)})
075:         *	List getContent(){...}
076:         * }
077:         * </pre>
078:         * The following is an XML instance document with mixed content
079:         * <pre><xmp>
080:         * <letterBody>
081:         * Dear Mr.<name>Robert Smith</name>
082:         * Your order of <quantity>1</quantity> <productName>Baby
083:         * Monitor</productName> shipped from our warehouse. ....
084:         * </letterBody>
085:         * </xmp></pre>
086:         * that can be constructed using following JAXB API calls.
087:         * <pre><xmp>
088:         * LetterBody lb = ObjectFactory.createLetterBody();
089:         * JAXBElement<LetterBody> lbe = ObjectFactory.createLetterBody(lb);
090:         * List gcl = lb.getContent();  //add mixed content to general content property.
091:         * gcl.add("Dear Mr.");  // add text information item as a String.
092:         * 
093:         * // add child element information item
094:         * gcl.add(ObjectFactory.createLetterBodyName("Robert Smith"));
095:         * gcl.add("Your order of "); // add text information item as a String
096:         * 
097:         * // add children element information items
098:         * gcl.add(ObjectFactory.
099:         * 	 		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:        }