1 /*2 * Copyright 2004 Sun Microsystems, Inc. All rights reserved.3 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.4 */5 6 package javax.xml.bind.annotation;7 8 import java.lang.annotation.Retention ;9 import java.lang.annotation.Target ;10 import static java.lang.annotation.RetentionPolicy.RUNTIME ;11 import static java.lang.annotation.ElementType.FIELD ;12 13 /**14 * Maps an enum constant in {@link Enum} type to XML representation. 15 * 16 * <p> <b>Usage</b> </p>17 *18 * <p> The <tt>@XmlEnumValue</tt> annotation can be used with the19 * following program elements: 20 * <ul> 21 * <li>enum constant</li>22 * </ul>23 *24 * <p>See "Package Specification" in javax.xml.bind.package javadoc for25 * additional common information.</p>26 *27 * <p>This annotation, together with {@link XmlEnum} provides a28 * mapping of enum type to XML representation.29 *30 * <p>An enum type is mapped to a schema simple type with enumeration31 * facets. The schema type is derived from the Java type specified in32 * <tt>@XmlEnum.value()</tt>. Each enum constant <tt>@XmlEnumValue</tt>33 * must have a valid lexical representation for the type34 * <tt>@XmlEnum.value()</tt> 35 *36 * <p> In the absence of this annotation, {@link Enum#name()} is used37 * as the XML representation.38 *39 * <p> <b>Example 1: </b>Map enum constant name -> enumeration facet</p>40 * <pre>41 * //Example: Code fragment42 * @XmlEnum(String.class)43 * public enum Card { CLUBS, DIAMONDS, HEARTS, SPADES }44 *45 * <!-- Example: XML Schema fragment -->46 * <xs:simpleType name="Card">47 * <xs:restriction base="xs:string"/>48 * <xs:enumeration value="CLUBS"/>49 * <xs:enumeration value="DIAMONDS"/>50 * <xs:enumeration value="HEARTS"/>51 * <xs:enumeration value="SPADES"/>52 * </xs:simpleType>53 * </pre>54 *55 * <p><b>Example 2: </b>Map enum constant name(value) -> enumeration facet </p>56 * <pre>57 * //Example: code fragment58 * @XmlType59 * @XmlEnum(Integer.class)60 * public enum Coin { 61 * @XmlEnumValue("1") PENNY(1),62 * @XmlEnumValue("5") NICKEL(5),63 * @XmlEnumValue("10") DIME(10),64 * @XmlEnumValue("25") QUARTER(25) }65 *66 * <!-- Example: XML Schema fragment -->67 * <xs:simpleType name="Coin">68 * <xs:restriction base="xs:int">69 * <xs:enumeration value="1"/>70 * <xs:enumeration value="5"/>71 * <xs:enumeration value="10"/>72 * <xs:enumeration value="25"/>73 * </xs:restriction>74 * </xs:simpleType>75 * </pre>76 *77 * <p><b>Example 3: </b>Map enum constant name -> enumeration facet </p>78 * 79 * <pre>80 * //Code fragment81 * @XmlType82 * @XmlEnum(Integer.class)83 * public enum Code {84 * @XmlEnumValue("1") ONE,85 * @XmlEnumValue("2") TWO;86 * }87 * 88 * <!-- Example: XML Schema fragment -->89 * <xs:simpleType name="Code">90 * <xs:restriction base="xs:int">91 * <xs:enumeration value="1"/>92 * <xs:enumeration value="2"/>93 * </xs:restriction>94 * </xs:simpleType>95 * </pre>96 *97 * @since JAXB 2.098 */99 @Retention (RUNTIME)100 @Target ({FIELD})101 public @interface XmlEnumValue {102 String value();103 }104