1 /* 2 * Copyright (c) 2004, 2015, 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 {@code @XmlEnumValue} 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 * {@code @XmlEnum.value()}. Each enum constant {@code @XmlEnumValue} 53 * must have a valid lexical representation for the type 54 * {@code @XmlEnum.value()} 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 {@literal ->} enumeration facet</p> 60 * <pre> 61 * //Example: Code fragment 62 * @XmlEnum(String.class) 63 * public enum Card { CLUBS, DIAMONDS, HEARTS, SPADES } 64 * {@code 65 * 66 * <!-- Example: XML Schema fragment --> 67 * <xs:simpleType name="Card"> 68 * <xs:restriction base="xs:string"/> 69 * <xs:enumeration value="CLUBS"/> 70 * <xs:enumeration value="DIAMONDS"/> 71 * <xs:enumeration value="HEARTS"/> 72 * <xs:enumeration value="SPADES"/> 73 * </xs:simpleType> 74 * }</pre> 75 * 76 * <p><b>Example 2: </b>Map enum constant name(value) {@literal ->} enumeration facet </p> 77 * <pre> 78 * //Example: code fragment 79 * @XmlType 80 * @XmlEnum(Integer.class) 81 * public enum Coin { 82 * @XmlEnumValue("1") PENNY(1), 83 * @XmlEnumValue("5") NICKEL(5), 84 * @XmlEnumValue("10") DIME(10), 85 * @XmlEnumValue("25") QUARTER(25) } 86 * {@code 87 * 88 * <!-- Example: XML Schema fragment --> 89 * <xs:simpleType name="Coin"> 90 * <xs:restriction base="xs:int"> 91 * <xs:enumeration value="1"/> 92 * <xs:enumeration value="5"/> 93 * <xs:enumeration value="10"/> 94 * <xs:enumeration value="25"/> 95 * </xs:restriction> 96 * </xs:simpleType> 97 * }</pre> 98 * 99 * <p><b>Example 3: </b>Map enum constant name {@literal ->} enumeration facet </p> 100 * 101 * <pre> 102 * //Code fragment 103 * @XmlType 104 * @XmlEnum(Integer.class) 105 * public enum Code { 106 * @XmlEnumValue("1") ONE, 107 * @XmlEnumValue("2") TWO; 108 * } 109 * {@code 110 * 111 * <!-- Example: XML Schema fragment --> 112 * <xs:simpleType name="Code"> 113 * <xs:restriction base="xs:int"> 114 * <xs:enumeration value="1"/> 115 * <xs:enumeration value="2"/> 116 * </xs:restriction> 117 * </xs:simpleType> 118 * }</pre> 119 * 120 * @since 1.6, JAXB 2.0 121 */ 122 @Retention(RUNTIME) 123 @Target({FIELD}) 124 public @interface XmlEnumValue { 125 String value(); 126 }