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 * @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 * <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 '' (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 }