1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.lang.enum;
18
19 import java.util.Iterator;
20 import java.util.List;
21
22 import org.apache.commons.lang.ClassUtils;
23
24 /**
25 * <p>Abstract superclass for type-safe enums with integer values suitable
26 * for use in <code>switch</code> statements.</p>
27 *
28 * <p><em>NOTE:</em>Due to the way in which Java ClassLoaders work, comparing
29 * <code>Enum</code> objects should always be done using the equals() method,
30 * not <code>==</code>. The equals() method will try <code>==</code> first so
31 * in most cases the effect is the same.</p>
32 *
33 * <p>To use this class, it must be subclassed. For example:</p>
34 *
35 * <pre>
36 * public final class JavaVersionEnum extends ValuedEnum {
37 * //standard enums for version of JVM
38 * public static final int JAVA1_0_VALUE = 100;
39 * public static final int JAVA1_1_VALUE = 110;
40 * public static final int JAVA1_2_VALUE = 120;
41 * public static final int JAVA1_3_VALUE = 130;
42 * public static final JavaVersionEnum JAVA1_0 = new JavaVersionEnum( "Java 1.0", JAVA1_0_VALUE );
43 * public static final JavaVersionEnum JAVA1_1 = new JavaVersionEnum( "Java 1.1", JAVA1_1_VALUE );
44 * public static final JavaVersionEnum JAVA1_2 = new JavaVersionEnum( "Java 1.2", JAVA1_2_VALUE );
45 * public static final JavaVersionEnum JAVA1_3 = new JavaVersionEnum( "Java 1.3", JAVA1_3_VALUE );
46 *
47 * private JavaVersionEnum(String name, int value) {
48 * super( name, value );
49 * }
50 *
51 * public static JavaVersionEnum getEnum(String javaVersion) {
52 * return (JavaVersionEnum) getEnum(JavaVersionEnum.class, javaVersion);
53 * }
54 *
55 * public static JavaVersionEnum getEnum(int javaVersion) {
56 * return (JavaVersionEnum) getEnum(JavaVersionEnum.class, javaVersion);
57 * }
58 *
59 * public static Map getEnumMap() {
60 * return getEnumMap(JavaVersionEnum.class);
61 * }
62 *
63 * public static List getEnumList() {
64 * return getEnumList(JavaVersionEnum.class);
65 * }
66 *
67 * public static Iterator iterator() {
68 * return iterator(JavaVersionEnum.class);
69 * }
70 * }
71 * </pre>
72 *
73 * <p>The above class could then be used as follows:</p>
74 *
75 * <pre>
76 * public void doSomething(JavaVersionEnum ver) {
77 * switch (ver.getValue()) {
78 * case JAVA1_0_VALUE:
79 * // ...
80 * break;
81 * case JAVA1_1_VALUE:
82 * // ...
83 * break;
84 * //...
85 * }
86 * }
87 * </pre>
88 *
89 * <p>As shown, each enum has a name and a value. These can be accessed using
90 * <code>getName</code> and <code>getValue</code>.</p>
91 *
92 * <p>The <code>getEnum</code> and <code>iterator</code> methods are recommended.
93 * Unfortunately, Java restrictions require these to be coded as shown in each subclass.
94 * An alternative choice is to use the {@link EnumUtils} class.</p>
95 *
96 * @deprecated Replaced by {@link org.apache.commons.lang.enums.ValuedEnum org.apache.commons.lang.enums.ValuedEnum}
97 * and will be removed in version 3.0. All classes in this package are deprecated and repackaged to
98 * {@link org.apache.commons.lang.enums} since <code>enum</code> is a Java 1.5 keyword.
99 * @see org.apache.commons.lang.enums.ValuedEnum
100 * @author Apache Avalon project
101 * @author Stephen Colebourne
102 * @since 1.0
103 * @version $Id: ValuedEnum.java 441929 2006-09-10 08:04:17Z bayard $
104 */
105 public abstract class ValuedEnum extends Enum {
106
107 /**
108 * Required for serialization support. Lang version 1.0.1 serial compatibility.
109 *
110 * @see java.io.Serializable
111 */
112 private static final long serialVersionUID = -7129650521543789085L;
113
114 /**
115 * The value contained in enum.
116 */
117 private final int iValue;
118
119 /**
120 * Constructor for enum item.
121 *
122 * @param name the name of enum item
123 * @param value the value of enum item
124 */
125 protected ValuedEnum(String name, int value) {
126 super(name);
127 iValue = value;
128 }
129
130 /**
131 * <p>Gets an <code>Enum</code> object by class and value.</p>
132 *
133 * <p>This method loops through the list of <code>Enum</code>,
134 * thus if there are many <code>Enum</code>s this will be
135 * slow.</p>
136 *
137 * @param enumClass the class of the <code>Enum</code> to get
138 * @param value the value of the <code>Enum</code> to get
139 * @return the enum object, or null if the enum does not exist
140 * @throws IllegalArgumentException if the enum class is <code>null</code>
141 */
142 protected static Enum getEnum(Class enumClass, int value) {
143 if (enumClass == null) {
144 throw new IllegalArgumentException("The Enum Class must not be null");
145 }
146 List list = Enum.getEnumList(enumClass);
147 for (Iterator it = list.iterator(); it.hasNext();) {
148 ValuedEnum enumeration = (ValuedEnum) it.next();
149 if (enumeration.getValue() == value) {
150 return enumeration;
151 }
152 }
153 return null;
154 }
155
156 /**
157 * <p>Get value of enum item.</p>
158 *
159 * @return the enum item's value.
160 */
161 public final int getValue() {
162 return iValue;
163 }
164
165 /**
166 * <p>Tests for order.</p>
167 *
168 * <p>The default ordering is numeric by value, but this
169 * can be overridden by subclasses.</p>
170 *
171 * @see java.lang.Comparable#compareTo(Object)
172 * @param other the other object to compare to
173 * @return -ve if this is less than the other object, +ve if greater than,
174 * <code>0</code> of equal
175 * @throws ClassCastException if other is not an <code>Enum</code>
176 * @throws NullPointerException if other is <code>null</code>
177 */
178 public int compareTo(Object other) {
179 return iValue - ((ValuedEnum) other).iValue;
180 }
181
182 /**
183 * <p>Human readable description of this <code>Enum</code> item.</p>
184 *
185 * @return String in the form <code>type[name=value]</code>, for example:
186 * <code>JavaVersion[Java 1.0=100]</code>. Note that the package name is
187 * stripped from the type name.
188 */
189 public String toString() {
190 if (iToString == null) {
191 String shortName = ClassUtils.getShortClassName(getEnumClass());
192 iToString = shortName + "[" + getName() + "=" + getValue() + "]";
193 }
194 return iToString;
195 }
196 }