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> </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 * @XmlElement(name="itemprice") 83 * public java.math.BigDecimal price; 84 * } 85 * 86 * <!-- Example: Local XML Schema element --> 87 * <xs:complexType name="USPrice"/> 88 * <xs:sequence> 89 * <xs:element name="itemprice" type="xs:decimal" minOccurs="0"/> 90 * </sequence> 91 * </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 * @XmlElement(nillable=true) 101 * public java.math.BigDecimal price; 102 * } 103 * 104 * <!-- Example: Local XML Schema element --> 105 * <xs:complexType name="USPrice"> 106 * <xs:sequence> 107 * <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="0"/> 108 * </sequence> 109 * </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 * @XmlElement(nillable=true, required=true) 118 * public java.math.BigDecimal price; 119 * } 120 * 121 * <!-- Example: Local XML Schema element --> 122 * <xs:complexType name="USPrice"> 123 * <xs:sequence> 124 * <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="1"/> 125 * </sequence> 126 * </xs:complexType> 127 * </pre> 128 * 129 * <p> <b>Example 4: </b>Map a JavaBean property to an XML element 130 * with anonymous type.</p> 131 * <p> 132 * See Example 6 in @{@link XmlType}. 133 * 134 * <p> 135 * @author Sekhar Vajjhala, Sun Microsystems, Inc. 136 * @since 1.6, JAXB 2.0 137 */ 138 139 @Retention(RUNTIME) @Target({FIELD, METHOD, PARAMETER}) 140 public @interface XmlElement { 141 /** 142 * Name of the XML Schema element. 143 * <p> If the value is "##default", then element name is derived from the 144 * JavaBean property name. 145 */ 146 String name() default "##default"; 147 148 /** 149 * Customize the element declaration to be nillable. 150 * <p>If nillable() is true, then the JavaBean property is 151 * mapped to a XML Schema nillable element declaration. 152 */ 153 boolean nillable() default false; 154 155 /** 156 * Customize the element declaration to be required. 157 * <p>If required() is true, then Javabean property is mapped to 158 * an XML schema element declaration with minOccurs="1". 159 * maxOccurs is "1" for a single valued property and "unbounded" 160 * for a multivalued property. 161 * <p>If required() is false, then the Javabean property is mapped 162 * to XML Schema element declaration with minOccurs="0". 163 * maxOccurs is "1" for a single valued property and "unbounded" 164 * for a multivalued property. 165 */ 166 167 boolean required() default false; 168 169 /** 170 * XML target namespace of the XML Schema element. 171 * <p> 172 * If the value is "##default", then the namespace is determined 173 * as follows: 174 * <ol> 175 * <li> 176 * If the enclosing package has {@link XmlSchema} annotation, 177 * and its {@link XmlSchema#elementFormDefault() elementFormDefault} 178 * is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of 179 * the enclosing class. 180 * 181 * <li> 182 * Otherwise '' (which produces unqualified element in the default 183 * namespace. 184 * </ol> 185 */ 186 String namespace() default "##default"; 187 188 /** 189 * Default value of this element. 190 * 191 * <p> 192 * The <pre>'\u0000'</pre> value specified as a default of this annotation element 193 * is used as a poor-man's substitute for null to allow implementations 194 * to recognize the 'no default value' state. 195 */ 196 String defaultValue() default "\u0000"; 197 198 /** 199 * The Java class being referenced. 200 */ 201 Class type() default DEFAULT.class; 202 203 /** 204 * Used in {@link XmlElement#type()} to 205 * signal that the type be inferred from the signature 206 * of the property. 207 */ 208 static final class DEFAULT {} 209 }