KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > lang > Enum


1 /*
2  * @(#)Enum.java 1.13 07/10/04
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.lang;
9
10 import java.io.Serializable JavaDoc;
11 import java.io.IOException JavaDoc;
12 import java.io.InvalidObjectException JavaDoc;
13 import java.io.ObjectInputStream JavaDoc;
14 import java.io.ObjectStreamException JavaDoc;
15
16 /**
17  * This is the common base class of all Java language enumeration types.
18  *
19  * @author Josh Bloch
20  * @author Neal Gafter
21  * @version 1.13, 10/04/07
22  * @since 1.5
23  */

24 public abstract class Enum<E extends Enum JavaDoc<E>>
25         implements Comparable JavaDoc<E>, Serializable JavaDoc {
26     /**
27      * The name of this enum constant, as declared in the enum declaration.
28      * Most programmers should use the {@link #toString} method rather than
29      * accessing this field.
30      */

31     private final String JavaDoc name;
32
33     /**
34      * Returns the name of this enum constant, exactly as declared in its
35      * enum declaration.
36      *
37      * <b>Most programmers should use the {@link #toString} method in
38      * preference to this one, as the toString method may return
39      * a more user-friendly name.</b> This method is designed primarily for
40      * use in specialized situations where correctness depends on getting the
41      * exact name, which will not vary from release to release.
42      *
43      * @return the name of this enum constant
44      */

45     public final String JavaDoc name() {
46     return name;
47     }
48
49     /**
50      * The ordinal of this enumeration constant (its position
51      * in the enum declaration, where the initial constant is assigned
52      * an ordinal of zero).
53      *
54      * Most programmers will have no use for this field. It is designed
55      * for use by sophisticated enum-based data structures, such as
56      * {@link java.util.EnumSet} and {@link java.util.EnumMap}.
57      */

58     private final int ordinal;
59
60     /**
61      * Returns the ordinal of this enumeration constant (its position
62      * in its enum declaration, where the initial constant is assigned
63      * an ordinal of zero).
64      *
65      * Most programmers will have no use for this method. It is
66      * designed for use by sophisticated enum-based data structures, such
67      * as {@link java.util.EnumSet} and {@link java.util.EnumMap}.
68      *
69      * @return the ordinal of this enumeration constant
70      */

71     public final int ordinal() {
72     return ordinal;
73     }
74
75     /**
76      * Sole constructor. Programmers cannot invoke this constructor.
77      * It is for use by code emitted by the compiler in response to
78      * enum type declarations.
79      *
80      * @param name - The name of this enum constant, which is the identifier
81      * used to declare it.
82      * @param ordinal - The ordinal of this enumeration constant (its position
83      * in the enum declaration, where the initial constant is assigned
84      * an ordinal of zero).
85      */

86     protected Enum(String JavaDoc name, int ordinal) {
87     this.name = name;
88     this.ordinal = ordinal;
89     }
90
91     /**
92      * Returns the name of this enum constant, as contained in the
93      * declaration. This method may be overridden, though it typically
94      * isn't necessary or desirable. An enum type should override this
95      * method when a more "programmer-friendly" string form exists.
96      *
97      * @return the name of this enum constant
98      */

99     public String JavaDoc toString() {
100     return name;
101     }
102
103     /**
104      * Returns true if the specified object is equal to this
105      * enum constant.
106      *
107      * @param other the object to be compared for equality with this object.
108      * @return true if the specified object is equal to this
109      * enum constant.
110      */

111     public final boolean equals(Object JavaDoc other) {
112         return this==other;
113     }
114
115     /**
116      * Returns a hash code for this enum constant.
117      *
118      * @return a hash code for this enum constant.
119      */

120     public final int hashCode() {
121         return System.identityHashCode(this);
122     }
123
124     /**
125      * Throws CloneNotSupportedException. This guarantees that enums
126      * are never cloned, which is necessary to preserve their "singleton"
127      * status.
128      *
129      * @return (never returns)
130      */

131     protected final Object JavaDoc clone() throws CloneNotSupportedException JavaDoc {
132     throw new CloneNotSupportedException JavaDoc();
133     }
134
135     /**
136      * Compares this enum with the specified object for order. Returns a
137      * negative integer, zero, or a positive integer as this object is less
138      * than, equal to, or greater than the specified object.
139      *
140      * Enum constants are only comparable to other enum constants of the
141      * same enum type. The natural order implemented by this
142      * method is the order in which the constants are declared.
143      */

144     public final int compareTo(E o) {
145     Enum JavaDoc other = (Enum JavaDoc)o;
146     Enum JavaDoc self = this;
147     if (self.getClass() != other.getClass() && // optimization
148
self.getDeclaringClass() != other.getDeclaringClass())
149         throw new ClassCastException JavaDoc();
150     return self.ordinal - other.ordinal;
151     }
152
153     /**
154      * Returns the Class object corresponding to this enum constant's
155      * enum type. Two enum constants e1 and e2 are of the
156      * same enum type if and only if
157      * e1.getDeclaringClass() == e2.getDeclaringClass().
158      * (The value returned by this method may differ from the one returned
159      * by the {@link Object#getClass} method for enum constants with
160      * constant-specific class bodies.)
161      *
162      * @return the Class object corresponding to this enum constant's
163      * enum type
164      */

165     public final Class JavaDoc<E> getDeclaringClass() {
166     Class JavaDoc clazz = getClass();
167     Class JavaDoc zuper = clazz.getSuperclass();
168     return (zuper == Enum JavaDoc.class) ? clazz : zuper;
169     }
170
171     /**
172      * Returns the enum constant of the specified enum type with the
173      * specified name. The name must match exactly an identifier used
174      * to declare an enum constant in this type. (Extraneous whitespace
175      * characters are not permitted.)
176      *
177      * @param enumType the <tt>Class</tt> object of the enum type from which
178      * to return a constant
179      * @param name the name of the constant to return
180      * @return the enum constant of the specified enum type with the
181      * specified name
182      * @throws IllegalArgumentException if the specified enum type has
183      * no constant with the specified name, or the specified
184      * class object does not represent an enum type
185      * @throws NullPointerException if <tt>enumType</tt> or <tt>name</tt>
186      * is null
187      * @since 1.5
188      */

189     public static <T extends Enum JavaDoc<T>> T valueOf(Class JavaDoc<T> enumType,
190                                                 String JavaDoc name) {
191         T result = enumType.enumConstantDirectory().get(name);
192         if (result != null)
193             return result;
194         if (name == null)
195             throw new NullPointerException JavaDoc("Name is null");
196         throw new IllegalArgumentException JavaDoc(
197             "No enum const " + enumType +"." + name);
198     }
199
200     /**
201       * prevent default deserialization
202       */

203     private void readObject(ObjectInputStream JavaDoc in) throws IOException JavaDoc,
204         ClassNotFoundException JavaDoc {
205             throw new InvalidObjectException JavaDoc("can't deserialize enum");
206     }
207
208     private void readObjectNoData() throws ObjectStreamException JavaDoc {
209         throw new InvalidObjectException JavaDoc("can't deserialize enum");
210     }
211 }
212
Popular Tags