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 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 {@code @XmlAttribute} 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 *
84 * <p> <b>Example 1: </b>Map a JavaBean property to an XML attribute.</p>
85 * <pre>
86 * //Example: Code fragment
87 * public class USPrice {
88 * @XmlAttribute
89 * public java.math.BigDecimal getPrice() {...} ;
90 * public void setPrice(java.math.BigDecimal ) {...};
91 * }
92 * {@code
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 * {@code
113 *
114 * <!-- Example: XML Schema fragment -->
115 * <xs:complexType name="foo">
116 * ...
117 * <xs:attribute name="items">
118 * <xs:simpleType>
119 * <xs:list itemType="xs:int"/>
120 * </xs:simpleType>
121 * </xs:complexType>
122 *
123 * }</pre>
124 * @author Sekhar Vajjhala, Sun Microsystems, Inc.
125 * @see XmlType
126 * @since 1.6, JAXB 2.0
127 */
128
129 @Retention(RUNTIME) @Target({FIELD, METHOD})
130 public @interface XmlAttribute {
131 /**
132 * Name of the XML Schema attribute. By default, the XML Schema
133 * attribute name is derived from the JavaBean property name.
134 *
135 */
136 String name() default "##default";
137
138 /**
139 * Specifies if the XML Schema attribute is optional or
140 * required. If true, then the JavaBean property is mapped to a
141 * XML Schema attribute that is required. Otherwise it is mapped
142 * to a XML Schema attribute that is optional.
143 *
144 */
145 boolean required() default false;
146
147 /**
148 * Specifies the XML target namespace of the XML Schema
149 * attribute.
150 *
151 */
152 String namespace() default "##default" ;
153 }