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 }