aoqi@0: /*
aoqi@0:  * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved.
aoqi@0:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
aoqi@0:  *
aoqi@0:  * This code is free software; you can redistribute it and/or modify it
aoqi@0:  * under the terms of the GNU General Public License version 2 only, as
aoqi@0:  * published by the Free Software Foundation.  Oracle designates this
aoqi@0:  * particular file as subject to the "Classpath" exception as provided
aoqi@0:  * by Oracle in the LICENSE file that accompanied this code.
aoqi@0:  *
aoqi@0:  * This code is distributed in the hope that it will be useful, but WITHOUT
aoqi@0:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
aoqi@0:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
aoqi@0:  * version 2 for more details (a copy is included in the LICENSE file that
aoqi@0:  * accompanied this code).
aoqi@0:  *
aoqi@0:  * You should have received a copy of the GNU General Public License version
aoqi@0:  * 2 along with this work; if not, write to the Free Software Foundation,
aoqi@0:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
aoqi@0:  *
aoqi@0:  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
aoqi@0:  * or visit www.oracle.com if you need additional information or have any
aoqi@0:  * questions.
aoqi@0:  */
aoqi@0: 
aoqi@0: package javax.xml.bind.annotation;
aoqi@0: 
aoqi@0: import java.lang.annotation.Retention;
aoqi@0: import java.lang.annotation.Target;
aoqi@0: 
aoqi@0: import static java.lang.annotation.ElementType.*;
aoqi@0: import static java.lang.annotation.RetentionPolicy.*;
aoqi@0: 
aoqi@0: /**
aoqi@0:  * <p>
aoqi@0:  * Maps a JavaBean property to a XML attribute.
aoqi@0:  *
aoqi@0:  * <p> <b>Usage</b> </p>
aoqi@0:  * <p>
aoqi@0:  * The <tt>@XmlAttribute</tt> annotation can be used with the
aoqi@0:  * following program elements:
aoqi@0:  * <ul>
aoqi@0:  *   <li> JavaBean property </li>
aoqi@0:  *   <li> field </li>
aoqi@0:  * </ul>
aoqi@0:  *
aoqi@0:  * <p> A static final field is mapped to a XML fixed attribute.
aoqi@0:  *
aoqi@0:  * <p>See "Package Specification" in javax.xml.bind.package javadoc for
aoqi@0:  * additional common information.</p>
aoqi@0:  *
aoqi@0:  * The usage is subject to the following constraints:
aoqi@0:  * <ul>
aoqi@0:  *   <li> If type of the field or the property is a collection
aoqi@0:  *        type, then the collection item type must be mapped to schema
aoqi@0:  *        simple type.
aoqi@0:  * <pre>
aoqi@0:  *     // Examples
aoqi@0:  *     &#64;XmlAttribute List&lt;Integer> items; //legal
aoqi@0:  *     &#64;XmlAttribute List&lt;Bar> foo; // illegal if Bar does not map to a schema simple type
aoqi@0:  * </pre>
aoqi@0:  *   </li>
aoqi@0:  *   <li> If the type of the field or the property is a non
aoqi@0:  *         collection type, then the type of the property or field
aoqi@0:  *         must map to a simple schema type.
aoqi@0:  * <pre>
aoqi@0:  *     // Examples
aoqi@0:  *     &#64;XmlAttribute int foo; // legal
aoqi@0:  *     &#64;XmlAttribute Foo foo; // illegal if Foo does not map to a schema simple type
aoqi@0:  * </pre>
aoqi@0:  *   </li>
aoqi@0:  *   <li> This annotation can be used with the following annotations:
aoqi@0:  *            {@link XmlID},
aoqi@0:  *            {@link XmlIDREF},
aoqi@0:  *            {@link XmlList},
aoqi@0:  *            {@link XmlSchemaType},
aoqi@0:  *            {@link XmlValue},
aoqi@0:  *            {@link XmlAttachmentRef},
aoqi@0:  *            {@link XmlMimeType},
aoqi@0:  *            {@link XmlInlineBinaryData},
aoqi@0:  *            {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.</li>
aoqi@0:  * </ul>
aoqi@0:  * </p>
aoqi@0:  *
aoqi@0:  * <p> <b>Example 1: </b>Map a JavaBean property to an XML attribute.</p>
aoqi@0:  * <pre>
aoqi@0:  *     //Example: Code fragment
aoqi@0:  *     public class USPrice {
aoqi@0:  *         &#64;XmlAttribute
aoqi@0:  *         public java.math.BigDecimal getPrice() {...} ;
aoqi@0:  *         public void setPrice(java.math.BigDecimal ) {...};
aoqi@0:  *     }
aoqi@0:  *
aoqi@0:  *     &lt;!-- Example: XML Schema fragment -->
aoqi@0:  *     &lt;xs:complexType name="USPrice">
aoqi@0:  *       &lt;xs:sequence>
aoqi@0:  *       &lt;/xs:sequence>
aoqi@0:  *       &lt;xs:attribute name="price" type="xs:decimal"/>
aoqi@0:  *     &lt;/xs:complexType>
aoqi@0:  * </pre>
aoqi@0:  *
aoqi@0:  * <p> <b>Example 2: </b>Map a JavaBean property to an XML attribute with anonymous type.</p>
aoqi@0:  * See Example 7 in @{@link XmlType}.
aoqi@0:  *
aoqi@0:  * <p> <b>Example 3: </b>Map a JavaBean collection property to an XML attribute.</p>
aoqi@0:  * <pre>
aoqi@0:  *     // Example: Code fragment
aoqi@0:  *     class Foo {
aoqi@0:  *         ...
aoqi@0:  *         &#64;XmlAttribute List&lt;Integer> items;
aoqi@0:  *     }
aoqi@0:  *
aoqi@0:  *     &lt;!-- Example: XML Schema fragment -->
aoqi@0:  *     &lt;xs:complexType name="foo">
aoqi@0:  *       ...
aoqi@0:  *       &lt;xs:attribute name="items">
aoqi@0:  *         &lt;xs:simpleType>
aoqi@0:  *           &lt;xs:list itemType="xs:int"/>
aoqi@0:  *         &lt;/xs:simpleType>
aoqi@0:  *     &lt;/xs:complexType>
aoqi@0:  *
aoqi@0:  * </pre>
aoqi@0:  * @author Sekhar Vajjhala, Sun Microsystems, Inc.
aoqi@0:  * @see XmlType
aoqi@0:  * @since JAXB2.0
aoqi@0:  */
aoqi@0: 
aoqi@0: @Retention(RUNTIME) @Target({FIELD, METHOD})
aoqi@0: public @interface XmlAttribute {
aoqi@0:     /**
aoqi@0:      * Name of the XML Schema attribute. By default, the XML Schema
aoqi@0:      * attribute name is derived from the JavaBean property name.
aoqi@0:      *
aoqi@0:      */
aoqi@0:     String name() default "##default";
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Specifies if the XML Schema attribute is optional or
aoqi@0:      * required. If true, then the JavaBean property is mapped to a
aoqi@0:      * XML Schema attribute that is required. Otherwise it is mapped
aoqi@0:      * to a XML Schema attribute that is optional.
aoqi@0:      *
aoqi@0:      */
aoqi@0:      boolean required() default false;
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Specifies the XML target namespace of the XML Schema
aoqi@0:      * attribute.
aoqi@0:      *
aoqi@0:      */
aoqi@0:     String namespace() default "##default" ;
aoqi@0: }