KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > lang > enum > ValuedEnum


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