1 /* 2 * Copyright (c) 2004, 2013, 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 java.lang.annotation.Retention; 29 import java.lang.annotation.Target; 30 31 import static java.lang.annotation.ElementType.*; 32 import static java.lang.annotation.RetentionPolicy.*; 33 34 /** 35 * <p> 36 * Maps a JavaBean property to a XML attribute. 37 * 38 * <p> <b>Usage</b> </p> 39 * <p> 40 * The <tt>@XmlAttribute</tt> annotation can be used with the 41 * following program elements: 42 * <ul> 43 * <li> JavaBean property </li> 44 * <li> field </li> 45 * </ul> 46 * 47 * <p> A static final field is mapped to a XML fixed attribute. 48 * 49 * <p>See "Package Specification" in javax.xml.bind.package javadoc for 50 * additional common information.</p> 51 * 52 * The usage is subject to the following constraints: 53 * <ul> 54 * <li> If type of the field or the property is a collection 55 * type, then the collection item type must be mapped to schema 56 * simple type. 57 * <pre> 58 * // Examples 59 * @XmlAttribute List<Integer> items; //legal 60 * @XmlAttribute List<Bar> foo; // illegal if Bar does not map to a schema simple type 61 * </pre> 62 * </li> 63 * <li> If the type of the field or the property is a non 64 * collection type, then the type of the property or field 65 * must map to a simple schema type. 66 * <pre> 67 * // Examples 68 * @XmlAttribute int foo; // legal 69 * @XmlAttribute Foo foo; // illegal if Foo does not map to a schema simple type 70 * </pre> 71 * </li> 72 * <li> This annotation can be used with the following annotations: 73 * {@link XmlID}, 74 * {@link XmlIDREF}, 75 * {@link XmlList}, 76 * {@link XmlSchemaType}, 77 * {@link XmlValue}, 78 * {@link XmlAttachmentRef}, 79 * {@link XmlMimeType}, 80 * {@link XmlInlineBinaryData}, 81 * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.</li> 82 * </ul> 83 * </p> 84 * 85 * <p> <b>Example 1: </b>Map a JavaBean property to an XML attribute.</p> 86 * <pre> 87 * //Example: Code fragment 88 * public class USPrice { 89 * @XmlAttribute 90 * public java.math.BigDecimal getPrice() {...} ; 91 * public void setPrice(java.math.BigDecimal ) {...}; 92 * } 93 * 94 * <!-- Example: XML Schema fragment --> 95 * <xs:complexType name="USPrice"> 96 * <xs:sequence> 97 * </xs:sequence> 98 * <xs:attribute name="price" type="xs:decimal"/> 99 * </xs:complexType> 100 * </pre> 101 * 102 * <p> <b>Example 2: </b>Map a JavaBean property to an XML attribute with anonymous type.</p> 103 * See Example 7 in @{@link XmlType}. 104 * 105 * <p> <b>Example 3: </b>Map a JavaBean collection property to an XML attribute.</p> 106 * <pre> 107 * // Example: Code fragment 108 * class Foo { 109 * ... 110 * @XmlAttribute List<Integer> items; 111 * } 112 * 113 * <!-- Example: XML Schema fragment --> 114 * <xs:complexType name="foo"> 115 * ... 116 * <xs:attribute name="items"> 117 * <xs:simpleType> 118 * <xs:list itemType="xs:int"/> 119 * </xs:simpleType> 120 * </xs:complexType> 121 * 122 * </pre> 123 * @author Sekhar Vajjhala, Sun Microsystems, Inc. 124 * @see XmlType 125 * @since 1.6, JAXB 2.0 126 */ 127 128 @Retention(RUNTIME) @Target({FIELD, METHOD}) 129 public @interface XmlAttribute { 130 /** 131 * Name of the XML Schema attribute. By default, the XML Schema 132 * attribute name is derived from the JavaBean property name. 133 * 134 */ 135 String name() default "##default"; 136 137 /** 138 * Specifies if the XML Schema attribute is optional or 139 * required. If true, then the JavaBean property is mapped to a 140 * XML Schema attribute that is required. Otherwise it is mapped 141 * to a XML Schema attribute that is optional. 142 * 143 */ 144 boolean required() default false; 145 146 /** 147 * Specifies the XML target namespace of the XML Schema 148 * attribute. 149 * 150 */ 151 String namespace() default "##default" ; 152 }