Source Code Cross Referenced for XmlValue.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 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 java.lang.annotation.Target;
009:        import java.lang.annotation.Retention;
010:        import static java.lang.annotation.ElementType.*;
011:        import static java.lang.annotation.RetentionPolicy.*;
012:
013:        /**
014:         * <p>
015:         * Enables mapping a class to a  XML Schema complex type with a
016:         * simpleContent or a XML Schema simple type. 
017:         * </p>
018:         *
019:         * <p>
020:         * <b> Usage: </b>
021:         * <p>
022:         * The <tt>@XmlValue</tt> annotation can be used with the following program
023:         * elements: 
024:         * <ul> 
025:         *   <li> a JavaBean property.</li>
026:         *   <li> non static, non transient field.</li>
027:         * </ul>
028:         * 
029:         * <p>See "Package Specification" in javax.xml.bind.package javadoc for
030:         * additional common information.</p>
031:         *
032:         * The usage is subject to the following usage constraints:
033:         * <ul>
034:         *   <li>At most one field or property can be annotated with the
035:         *       <tt>@XmlValue</tt> annotation. </li> 
036:         *
037:         *   <li><tt>@XmlValue</tt> can be used with the following
038:         *   annotations: {@link XmlList}. However this is redundant since
039:         *   {@link XmlList} maps a type to a simple schema type that derives by
040:         *   list just as {@link XmlValue} would. </li>
041:         *
042:         *   <li>If the type of the field or property is a collection type,
043:         *       then the collection item type must map to a simple schema
044:         *       type.  </li>
045:         * 
046:         *   <li>If the type of the field or property is not a collection
047:         *       type, then the type must map to a XML Schema simple type. </li>
048:         *
049:         * </ul>
050:         * </p>
051:         * <p>
052:         * If the annotated JavaBean property is the sole class member being
053:         * mapped to XML Schema construct, then the class is mapped to a
054:         * simple type. 
055:         *
056:         * If there are additional JavaBean properties (other than the
057:         * JavaBean property annotated with <tt>@XmlValue</tt> annotation)
058:         * that are mapped to XML attributes, then the class is mapped to a
059:         * complex type with simpleContent.
060:         * </p>
061:         *
062:         * <p> <b> Example 1: </b> Map a class to XML Schema simpleType</p>
063:         *
064:         *   <pre>
065:         * 
066:         *     // Example 1: Code fragment
067:         *     public class USPrice {
068:         *         &#64;XmlValue
069:         *         public java.math.BigDecimal price;
070:         *     }
071:         *  
072:         *     &lt;!-- Example 1: XML Schema fragment -->
073:         *     &lt;xs:simpleType name="USPrice">
074:         *       &lt;xs:restriction base="xs:decimal"/>
075:         *     &lt;/xs:simpleType>
076:         *
077:         *   </pre>
078:         * 
079:         * <p><b> Example 2: </b> Map a class to XML Schema complexType with
080:         *        with simpleContent.</p>
081:         * 
082:         *   <pre>
083:         *
084:         *   // Example 2: Code fragment
085:         *   public class InternationalPrice {
086:         *       &#64;XmlValue
087:         *       public java.math.BigDecimal price;
088:         * 
089:         *       &#64;XmlAttribute
090:         *       public String currency;
091:         *   }
092:         *  
093:         *   &lt;!-- Example 2: XML Schema fragment -->
094:         *   &lt;xs:complexType name="InternationalPrice">
095:         *     &lt;xs:simpleContent>
096:         *       &lt;xs:extension base="xs:decimal">
097:         *         &lt;xs:attribute name="currency" type="xs:string"/>
098:         *       &lt;/xs:extension>
099:         *     &lt;/xs:simpleContent>
100:         *   &lt;/xs:complexType> 
101:         *
102:         *   </pre>
103:         * </p>
104:         *
105:         * @author Sekhar Vajjhala, Sun Microsystems, Inc.
106:         * @see XmlType
107:         * @since JAXB2.0
108:         * @version $Revision: 1.6 $
109:         */
110:
111:        @Retention(RUNTIME)
112:        @Target({FIELD,METHOD})
113:        public @interface XmlValue {
114:        }