ohair@286: /* ohair@286: * Copyright (c) 2004, 2010, Oracle and/or its affiliates. All rights reserved. ohair@286: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. ohair@286: * ohair@286: * This code is free software; you can redistribute it and/or modify it ohair@286: * under the terms of the GNU General Public License version 2 only, as ohair@286: * published by the Free Software Foundation. Oracle designates this ohair@286: * particular file as subject to the "Classpath" exception as provided ohair@286: * by Oracle in the LICENSE file that accompanied this code. ohair@286: * ohair@286: * This code is distributed in the hope that it will be useful, but WITHOUT ohair@286: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or ohair@286: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License ohair@286: * version 2 for more details (a copy is included in the LICENSE file that ohair@286: * accompanied this code). ohair@286: * ohair@286: * You should have received a copy of the GNU General Public License version ohair@286: * 2 along with this work; if not, write to the Free Software Foundation, ohair@286: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. ohair@286: * ohair@286: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@286: * or visit www.oracle.com if you need additional information or have any ohair@286: * questions. ohair@286: */ ohair@286: ohair@286: package javax.xml.bind.annotation; ohair@286: ohair@286: import java.lang.annotation.Retention; ohair@286: import java.lang.annotation.Target; ohair@286: import static java.lang.annotation.RetentionPolicy.RUNTIME; ohair@286: import static java.lang.annotation.ElementType.FIELD; ohair@286: ohair@286: /** ohair@286: * Maps an enum constant in {@link Enum} type to XML representation. ohair@286: * ohair@286: *

Usage

ohair@286: * ohair@286: *

The @XmlEnumValue annotation can be used with the ohair@286: * following program elements: ohair@286: *

ohair@286: * ohair@286: *

See "Package Specification" in javax.xml.bind.package javadoc for ohair@286: * additional common information.

ohair@286: * ohair@286: *

This annotation, together with {@link XmlEnum} provides a ohair@286: * mapping of enum type to XML representation. ohair@286: * ohair@286: *

An enum type is mapped to a schema simple type with enumeration ohair@286: * facets. The schema type is derived from the Java type specified in ohair@286: * @XmlEnum.value(). Each enum constant @XmlEnumValue ohair@286: * must have a valid lexical representation for the type ohair@286: * @XmlEnum.value() ohair@286: * ohair@286: *

In the absence of this annotation, {@link Enum#name()} is used ohair@286: * as the XML representation. ohair@286: * ohair@286: *

Example 1: Map enum constant name -> enumeration facet

ohair@286: * 
ohair@286:  *     //Example: Code fragment
ohair@286:  *     @XmlEnum(String.class)
ohair@286:  *     public enum Card { CLUBS, DIAMONDS, HEARTS, SPADES }
ohair@286:  *
ohair@286:  *     <!-- Example: XML Schema fragment -->
ohair@286:  *     <xs:simpleType name="Card">
ohair@286:  *       <xs:restriction base="xs:string"/>
ohair@286:  *         <xs:enumeration value="CLUBS"/>
ohair@286:  *         <xs:enumeration value="DIAMONDS"/>
ohair@286:  *         <xs:enumeration value="HEARTS"/>
ohair@286:  *         <xs:enumeration value="SPADES"/>
ohair@286:  *     </xs:simpleType>
ohair@286:  *
ohair@286: * ohair@286: *

Example 2: Map enum constant name(value) -> enumeration facet

ohair@286: * 
ohair@286:  *     //Example: code fragment
ohair@286:  *     @XmlType
ohair@286:  *     @XmlEnum(Integer.class)
ohair@286:  *     public enum Coin {
ohair@286:  *         @XmlEnumValue("1") PENNY(1),
ohair@286:  *         @XmlEnumValue("5") NICKEL(5),
ohair@286:  *         @XmlEnumValue("10") DIME(10),
ohair@286:  *         @XmlEnumValue("25") QUARTER(25) }
ohair@286:  *
ohair@286:  *     <!-- Example: XML Schema fragment -->
ohair@286:  *     <xs:simpleType name="Coin">
ohair@286:  *       <xs:restriction base="xs:int">
ohair@286:  *         <xs:enumeration value="1"/>
ohair@286:  *         <xs:enumeration value="5"/>
ohair@286:  *         <xs:enumeration value="10"/>
ohair@286:  *         <xs:enumeration value="25"/>
ohair@286:  *       </xs:restriction>
ohair@286:  *     </xs:simpleType>
ohair@286:  *
ohair@286: * ohair@286: *

Example 3: Map enum constant name -> enumeration facet

ohair@286: * ohair@286: * 
ohair@286:  *     //Code fragment
ohair@286:  *     @XmlType
ohair@286:  *     @XmlEnum(Integer.class)
ohair@286:  *     public enum Code {
ohair@286:  *         @XmlEnumValue("1") ONE,
ohair@286:  *         @XmlEnumValue("2") TWO;
ohair@286:  *     }
ohair@286:  *
ohair@286:  *     <!-- Example: XML Schema fragment -->
ohair@286:  *     <xs:simpleType name="Code">
ohair@286:  *       <xs:restriction base="xs:int">
ohair@286:  *         <xs:enumeration value="1"/>
ohair@286:  *         <xs:enumeration value="2"/>
ohair@286:  *       </xs:restriction>
ohair@286:  *     </xs:simpleType>
ohair@286:  *
ohair@286: * ohair@286: * @since JAXB 2.0 ohair@286: */ ohair@286: @Retention(RUNTIME) ohair@286: @Target({FIELD}) ohair@286: public @interface XmlEnumValue { ohair@286: String value(); ohair@286: }