001:/*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:package org.apache.commons.lang.enum;
018:
019:import java.util.Iterator;
020:import java.util.List;
021:
022:import org.apache.commons.lang.ClassUtils;
023:
024:/**
025: * <p>Abstract superclass for type-safe enums with integer values suitable
026: * for use in <code>switch</code> statements.</p>
027: *
028: * <p><em>NOTE:</em>Due to the way in which Java ClassLoaders work, comparing
029: * <code>Enum</code> objects should always be done using the equals() method,
030: * not <code>==</code>. The equals() method will try <code>==</code> first so
031: * in most cases the effect is the same.</p>
032: *
033: * <p>To use this class, it must be subclassed. For example:</p>
034: *
035: * <pre>
036: * public final class JavaVersionEnum extends ValuedEnum {
037: * //standard enums for version of JVM
038: * public static final int JAVA1_0_VALUE = 100;
039: * public static final int JAVA1_1_VALUE = 110;
040: * public static final int JAVA1_2_VALUE = 120;
041: * public static final int JAVA1_3_VALUE = 130;
042: * public static final JavaVersionEnum JAVA1_0 = new JavaVersionEnum( "Java 1.0", JAVA1_0_VALUE );
043: * public static final JavaVersionEnum JAVA1_1 = new JavaVersionEnum( "Java 1.1", JAVA1_1_VALUE );
044: * public static final JavaVersionEnum JAVA1_2 = new JavaVersionEnum( "Java 1.2", JAVA1_2_VALUE );
045: * public static final JavaVersionEnum JAVA1_3 = new JavaVersionEnum( "Java 1.3", JAVA1_3_VALUE );
046: *
047: * private JavaVersionEnum(String name, int value) {
048: * super( name, value );
049: * }
050: *
051: * public static JavaVersionEnum getEnum(String javaVersion) {
052: * return (JavaVersionEnum) getEnum(JavaVersionEnum.class, javaVersion);
053: * }
054: *
055: * public static JavaVersionEnum getEnum(int javaVersion) {
056: * return (JavaVersionEnum) getEnum(JavaVersionEnum.class, javaVersion);
057: * }
058: *
059: * public static Map getEnumMap() {
060: * return getEnumMap(JavaVersionEnum.class);
061: * }
062: *
063: * public static List getEnumList() {
064: * return getEnumList(JavaVersionEnum.class);
065: * }
066: *
067: * public static Iterator iterator() {
068: * return iterator(JavaVersionEnum.class);
069: * }
070: * }
071: * </pre>
072: *
073: * <p>The above class could then be used as follows:</p>
074: *
075: * <pre>
076: * public void doSomething(JavaVersionEnum ver) {
077: * switch (ver.getValue()) {
078: * case JAVA1_0_VALUE:
079: * // ...
080: * break;
081: * case JAVA1_1_VALUE:
082: * // ...
083: * break;
084: * //...
085: * }
086: * }
087: * </pre>
088: *
089: * <p>As shown, each enum has a name and a value. These can be accessed using
090: * <code>getName</code> and <code>getValue</code>.</p>
091: *
092: * <p>The <code>getEnum</code> and <code>iterator</code> methods are recommended.
093: * Unfortunately, Java restrictions require these to be coded as shown in each subclass.
094: * An alternative choice is to use the {@link EnumUtils} class.</p>
095: *
096: * @deprecated Replaced by {@link org.apache.commons.lang.enums.ValuedEnum org.apache.commons.lang.enums.ValuedEnum}
097: * and will be removed in version 3.0. All classes in this package are deprecated and repackaged to
098: * {@link org.apache.commons.lang.enums} since <code>enum</code> is a Java 1.5 keyword.
099: * @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:}
|