1 /* 2 * Copyright (c) 2004, 2010, 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 import static java.lang.annotation.RetentionPolicy.RUNTIME; 31 import static java.lang.annotation.ElementType.FIELD; 32 33 /** 34 * Maps an enum constant in {@link Enum} type to XML representation. 35 * 36 * <p> <b>Usage</b> </p> 37 * 38 * <p> The <tt>@XmlEnumValue</tt> annotation can be used with the 39 * following program elements: 40 * <ul> 41 * <li>enum constant</li> 42 * </ul> 43 * 44 * <p>See "Package Specification" in javax.xml.bind.package javadoc for 45 * additional common information.</p> 46 * 47 * <p>This annotation, together with {@link XmlEnum} provides a 48 * mapping of enum type to XML representation. 49 * 50 * <p>An enum type is mapped to a schema simple type with enumeration 51 * facets. The schema type is derived from the Java type specified in 52 * <tt>@XmlEnum.value()</tt>. Each enum constant <tt>@XmlEnumValue</tt> 53 * must have a valid lexical representation for the type 54 * <tt>@XmlEnum.value()</tt> 55 * 56 * <p> In the absence of this annotation, {@link Enum#name()} is used 57 * as the XML representation. 58 * 59 * <p> <b>Example 1: </b>Map enum constant name -> enumeration facet</p> 60 * <pre> 61 * //Example: Code fragment 62 * @XmlEnum(String.class) 63 * public enum Card { CLUBS, DIAMONDS, HEARTS, SPADES } 64 * 65 * <!-- Example: XML Schema fragment --> 66 * <xs:simpleType name="Card"> 67 * <xs:restriction base="xs:string"/> 68 * <xs:enumeration value="CLUBS"/> 69 * <xs:enumeration value="DIAMONDS"/> 70 * <xs:enumeration value="HEARTS"/> 71 * <xs:enumeration value="SPADES"/> 72 * </xs:simpleType> 73 * </pre> 74 * 75 * <p><b>Example 2: </b>Map enum constant name(value) -> enumeration facet </p> 76 * <pre> 77 * //Example: code fragment 78 * @XmlType 79 * @XmlEnum(Integer.class) 80 * public enum Coin { 81 * @XmlEnumValue("1") PENNY(1), 82 * @XmlEnumValue("5") NICKEL(5), 83 * @XmlEnumValue("10") DIME(10), 84 * @XmlEnumValue("25") QUARTER(25) } 85 * 86 * <!-- Example: XML Schema fragment --> 87 * <xs:simpleType name="Coin"> 88 * <xs:restriction base="xs:int"> 89 * <xs:enumeration value="1"/> 90 * <xs:enumeration value="5"/> 91 * <xs:enumeration value="10"/> 92 * <xs:enumeration value="25"/> 93 * </xs:restriction> 94 * </xs:simpleType> 95 * </pre> 96 * 97 * <p><b>Example 3: </b>Map enum constant name -> enumeration facet </p> 98 * 99 * <pre> 100 * //Code fragment 101 * @XmlType 102 * @XmlEnum(Integer.class) 103 * public enum Code { 104 * @XmlEnumValue("1") ONE, 105 * @XmlEnumValue("2") TWO; 106 * } 107 * 108 * <!-- Example: XML Schema fragment --> 109 * <xs:simpleType name="Code"> 110 * <xs:restriction base="xs:int"> 111 * <xs:enumeration value="1"/> 112 * <xs:enumeration value="2"/> 113 * </xs:restriction> 114 * </xs:simpleType> 115 * </pre> 116 * 117 * @since JAXB 2.0 118 */ 119 @Retention(RUNTIME) 120 @Target({FIELD}) 121 public @interface XmlEnumValue { 122 String value(); 123 }