1 /*
   2  * Copyright (c) 2004, 2011, 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 javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
  29 import java.lang.annotation.Retention;
  30 import java.lang.annotation.Target;
  31 
  32 import static java.lang.annotation.ElementType.*;
  33 import static java.lang.annotation.ElementType.PARAMETER;
  34 import static java.lang.annotation.RetentionPolicy.*;
  35 
  36 /**
  37  * Maps a JavaBean property to a XML element derived from property name.
  38  *
  39  * <p> <b>Usage</b> </p>
  40  * <p>
  41  * <tt>@XmlElement</tt> annotation can be used with the following program
  42  * elements:
  43  * <ul>
  44  *   <li> a JavaBean property </li>
  45  *   <li> non static, non transient field </li>
  46  *   <li> within {@link XmlElements}
  47  * <p>
  48  *
  49  * </ul>
  50  *
  51  * The usage is subject to the following constraints:
  52  * <ul>
  53  *   <li> This annotation can be used with following annotations:
  54  *            {@link XmlID},
  55  *            {@link XmlIDREF},
  56  *            {@link XmlList},
  57  *            {@link XmlSchemaType},
  58  *            {@link XmlValue},
  59  *            {@link XmlAttachmentRef},
  60  *            {@link XmlMimeType},
  61  *            {@link XmlInlineBinaryData},
  62  *            {@link XmlElementWrapper},
  63  *            {@link XmlJavaTypeAdapter}</li>
  64  *   <li> if the type of JavaBean property is a collection type of
  65  *        array, an indexed property, or a parameterized list, and
  66  *        this annotation is used with {@link XmlElements} then,
  67  *        <tt>@XmlElement.type()</tt> must be DEFAULT.class since the
  68  *        collection item type is already known. </li>
  69  * </ul>
  70  *
  71  * <p>
  72  * A JavaBean property, when annotated with @XmlElement annotation
  73  * is mapped to a local element in the XML Schema complex type to
  74  * which the containing class is mapped.
  75  *
  76  * <p>
  77  * <b>Example 1: </b> Map a public non static non final field to local
  78  * element
  79  * <pre>
  80  *     //Example: Code fragment
  81  *     public class USPrice {
  82  *         &#64;XmlElement(name="itemprice")
  83  *         public java.math.BigDecimal price;
  84  *     }
  85  *
  86  *     &lt;!-- Example: Local XML Schema element -->
  87  *     &lt;xs:complexType name="USPrice"/>
  88  *       &lt;xs:sequence>
  89  *         &lt;xs:element name="itemprice" type="xs:decimal" minOccurs="0"/>
  90  *       &lt;/sequence>
  91  *     &lt;/xs:complexType>
  92  *   </pre>
  93  * <p>
  94  *
  95  * <b> Example 2: </b> Map a field to a nillable element.
  96  *   <pre>
  97  *
  98  *     //Example: Code fragment
  99  *     public class USPrice {
 100  *         &#64;XmlElement(nillable=true)
 101  *         public java.math.BigDecimal price;
 102  *     }
 103  *
 104  *     &lt;!-- Example: Local XML Schema element -->
 105  *     &lt;xs:complexType name="USPrice">
 106  *       &lt;xs:sequence>
 107  *         &lt;xs:element name="price" type="xs:decimal" nillable="true" minOccurs="0"/>
 108  *       &lt;/sequence>
 109  *     &lt;/xs:complexType>
 110  *   </pre>
 111  * <p>
 112  * <b> Example 3: </b> Map a field to a nillable, required element.
 113  *   <pre>
 114  *
 115  *     //Example: Code fragment
 116  *     public class USPrice {
 117  *         &#64;XmlElement(nillable=true, required=true)
 118  *         public java.math.BigDecimal price;
 119  *     }
 120  *
 121  *     &lt;!-- Example: Local XML Schema element -->
 122  *     &lt;xs:complexType name="USPrice">
 123  *       &lt;xs:sequence>
 124  *         &lt;xs:element name="price" type="xs:decimal" nillable="true" minOccurs="1"/>
 125  *       &lt;/sequence>
 126  *     &lt;/xs:complexType>
 127  *   </pre>
 128  * <p>
 129  *
 130  * <p> <b>Example 4: </b>Map a JavaBean property to an XML element
 131  * with anonymous type.</p>
 132  * <p>
 133  * See Example 6 in @{@link XmlType}.
 134  *
 135  * <p>
 136  * @author Sekhar Vajjhala, Sun Microsystems, Inc.
 137  * @since JAXB2.0
 138  */
 139 
 140 @Retention(RUNTIME) @Target({FIELD, METHOD, PARAMETER})
 141 public @interface XmlElement {
 142     /**
 143      * Name of the XML Schema element.
 144      * <p> If the value is "##default", then element name is derived from the
 145      * JavaBean property name.
 146      */
 147     String name() default "##default";
 148 
 149     /**
 150      * Customize the element declaration to be nillable.
 151      * <p>If nillable() is true, then the JavaBean property is
 152      * mapped to a XML Schema nillable element declaration.
 153      */
 154     boolean nillable() default false;
 155 
 156     /**
 157      * Customize the element declaration to be required.
 158      * <p>If required() is true, then Javabean property is mapped to
 159      * an XML schema element declaration with minOccurs="1".
 160      * maxOccurs is "1" for a single valued property and "unbounded"
 161      * for a multivalued property.
 162      * <p>If required() is false, then the Javabean property is mapped
 163      * to XML Schema element declaration with minOccurs="0".
 164      * maxOccurs is "1" for a single valued property and "unbounded"
 165      * for a multivalued property.
 166      */
 167 
 168     boolean required() default false;
 169 
 170     /**
 171      * XML target namespace of the XML Schema element.
 172      * <p>
 173      * If the value is "##default", then the namespace is determined
 174      * as follows:
 175      * <ol>
 176      *  <li>
 177      *  If the enclosing package has {@link XmlSchema} annotation,
 178      *  and its {@link XmlSchema#elementFormDefault() elementFormDefault}
 179      *  is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of
 180      *  the enclosing class.
 181      *
 182      *  <li>
 183      *  Otherwise &#39;&#39; (which produces unqualified element in the default
 184      *  namespace.
 185      * </ol>
 186      */
 187     String namespace() default "##default";
 188 
 189     /**
 190      * Default value of this element.
 191      *
 192      * <p>
 193      * The <pre>'\u0000'</pre> value specified as a default of this annotation element
 194      * is used as a poor-man's substitute for null to allow implementations
 195      * to recognize the 'no default value' state.
 196      */
 197     String defaultValue() default "\u0000";
 198 
 199     /**
 200      * The Java class being referenced.
 201      */
 202     Class type() default DEFAULT.class;
 203 
 204     /**
 205      * Used in {@link XmlElement#type()} to
 206      * signal that the type be inferred from the signature
 207      * of the property.
 208      */
 209     static final class DEFAULT {}
 210 }