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