001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.bind.annotation;
027
028 import java.lang.annotation.Retention;
029 import java.lang.annotation.Target;
030
031 import static java.lang.annotation.ElementType.*;
032 import static java.lang.annotation.RetentionPolicy.*;
033
034 /**
035 * <p>
036 * Maps a JavaBean property to a XML attribute.
037 *
038 * <p> <b>Usage</b> </p>
039 * <p>
040 * The <tt>@XmlAttribute</tt> annotation can be used with the
041 * following program elements:
042 * <ul>
043 * <li> JavaBean property </li>
044 * <li> field </li>
045 * </ul>
046 *
047 * <p> A static final field is mapped to a XML fixed attribute.
048 *
049 * <p>See "Package Specification" in javax.xml.bind.package javadoc for
050 * additional common information.</p>
051 *
052 * The usage is subject to the following constraints:
053 * <ul>
054 * <li> If type of the field or the property is a collection
055 * type, then the collection item type must be mapped to schema
056 * simple type.
057 * <pre>
058 * // Examples
059 * @XmlAttribute List<Integer> items; //legal
060 * @XmlAttribute List<Bar> foo; // illegal if Bar does not map to a schema simple type
061 * </pre>
062 * </li>
063 * <li> If the type of the field or the property is a non
064 * collection type, then the type of the property or field
065 * must map to a simple schema type.
066 * <pre>
067 * // Examples
068 * @XmlAttribute int foo; // legal
069 * @XmlAttribute Foo foo; // illegal if Foo does not map to a schema simple type
070 * </pre>
071 * </li>
072 * <li> This annotation can be used with the following annotations:
073 * {@link XmlID},
074 * {@link XmlIDREF},
075 * {@link XmlList},
076 * {@link XmlSchemaType},
077 * {@link XmlValue},
078 * {@link XmlAttachmentRef},
079 * {@link XmlMimeType},
080 * {@link XmlInlineBinaryData},
081 * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}</li>.
082 * </ul>
083 * </p>
084 *
085 * <p> <b>Example 1: </b>Map a JavaBean property to an XML attribute.</p>
086 * <pre>
087 * //Example: Code fragment
088 * public class USPrice {
089 * @XmlAttribute
090 * public java.math.BigDecimal getPrice() {...} ;
091 * public void setPrice(java.math.BigDecimal ) {...};
092 * }
093 *
094 * <!-- Example: XML Schema fragment -->
095 * <xs:complexType name="USPrice">
096 * <xs:sequence>
097 * </xs:sequence>
098 * <xs:attribute name="price" type="xs:decimal"/>
099 * </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 * @version $Revision: 1.13 $
125 * @see XmlType
126 * @since JAXB2.0
127 */
128
129 @Retention(RUNTIME)
130 @Target({FIELD,METHOD})
131 public @interface XmlAttribute {
132 /**
133 * Name of the XML Schema attribute. By default, the XML Schema
134 * attribute name is derived from the JavaBean property name.
135 *
136 */
137 String name() default "##default";
138
139 /**
140 * Specifies if the XML Schema attribute is optional or
141 * required. If true, then the JavaBean property is mapped to a
142 * XML Schema attribute that is required. Otherwise it is mapped
143 * to a XML Schema attribute that is optional.
144 *
145 */
146 boolean required() default false;
147
148 /**
149 * Specifies the XML target namespace of the XML Schema
150 * attribute.
151 *
152 */
153 String namespace() default "##default";
154 }
|