001 /*
002 * Copyright 2003-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.lang;
027
028 import java.io.Serializable;
029 import java.io.IOException;
030 import java.io.InvalidObjectException;
031 import java.io.ObjectInputStream;
032 import java.io.ObjectStreamException;
033
034 /**
035 * This is the common base class of all Java language enumeration types.
036 *
037 * @author Josh Bloch
038 * @author Neal Gafter
039 * @version 1.24, 05/05/07
040 * @see Class#getEnumConstants()
041 * @since 1.5
042 */
043 public abstract class Enum<E extends Enum<E>> implements Comparable<E>,
044 Serializable {
045 /**
046 * The name of this enum constant, as declared in the enum declaration.
047 * Most programmers should use the {@link #toString} method rather than
048 * accessing this field.
049 */
050 private final String name;
051
052 /**
053 * Returns the name of this enum constant, exactly as declared in its
054 * enum declaration.
055 *
056 * <b>Most programmers should use the {@link #toString} method in
057 * preference to this one, as the toString method may return
058 * a more user-friendly name.</b> This method is designed primarily for
059 * use in specialized situations where correctness depends on getting the
060 * exact name, which will not vary from release to release.
061 *
062 * @return the name of this enum constant
063 */
064 public final String name() {
065 return name;
066 }
067
068 /**
069 * The ordinal of this enumeration constant (its position
070 * in the enum declaration, where the initial constant is assigned
071 * an ordinal of zero).
072 *
073 * Most programmers will have no use for this field. It is designed
074 * for use by sophisticated enum-based data structures, such as
075 * {@link java.util.EnumSet} and {@link java.util.EnumMap}.
076 */
077 private final int ordinal;
078
079 /**
080 * Returns the ordinal of this enumeration constant (its position
081 * in its enum declaration, where the initial constant is assigned
082 * an ordinal of zero).
083 *
084 * Most programmers will have no use for this method. It is
085 * designed for use by sophisticated enum-based data structures, such
086 * as {@link java.util.EnumSet} and {@link java.util.EnumMap}.
087 *
088 * @return the ordinal of this enumeration constant
089 */
090 public final int ordinal() {
091 return ordinal;
092 }
093
094 /**
095 * Sole constructor. Programmers cannot invoke this constructor.
096 * It is for use by code emitted by the compiler in response to
097 * enum type declarations.
098 *
099 * @param name - The name of this enum constant, which is the identifier
100 * used to declare it.
101 * @param ordinal - The ordinal of this enumeration constant (its position
102 * in the enum declaration, where the initial constant is assigned
103 * an ordinal of zero).
104 */
105 protected Enum(String name, int ordinal) {
106 this .name = name;
107 this .ordinal = ordinal;
108 }
109
110 /**
111 * Returns the name of this enum constant, as contained in the
112 * declaration. This method may be overridden, though it typically
113 * isn't necessary or desirable. An enum type should override this
114 * method when a more "programmer-friendly" string form exists.
115 *
116 * @return the name of this enum constant
117 */
118 public String toString() {
119 return name;
120 }
121
122 /**
123 * Returns true if the specified object is equal to this
124 * enum constant.
125 *
126 * @param other the object to be compared for equality with this object.
127 * @return true if the specified object is equal to this
128 * enum constant.
129 */
130 public final boolean equals(Object other) {
131 return this == other;
132 }
133
134 /**
135 * Returns a hash code for this enum constant.
136 *
137 * @return a hash code for this enum constant.
138 */
139 public final int hashCode() {
140 return super .hashCode();
141 }
142
143 /**
144 * Throws CloneNotSupportedException. This guarantees that enums
145 * are never cloned, which is necessary to preserve their "singleton"
146 * status.
147 *
148 * @return (never returns)
149 */
150 protected final Object clone() throws CloneNotSupportedException {
151 throw new CloneNotSupportedException();
152 }
153
154 /**
155 * Compares this enum with the specified object for order. Returns a
156 * negative integer, zero, or a positive integer as this object is less
157 * than, equal to, or greater than the specified object.
158 *
159 * Enum constants are only comparable to other enum constants of the
160 * same enum type. The natural order implemented by this
161 * method is the order in which the constants are declared.
162 */
163 public final int compareTo(E o) {
164 Enum other = (Enum) o;
165 Enum self = this ;
166 if (self.getClass() != other.getClass() && // optimization
167 self.getDeclaringClass() != other.getDeclaringClass())
168 throw new ClassCastException();
169 return self.ordinal - other.ordinal;
170 }
171
172 /**
173 * Returns the Class object corresponding to this enum constant's
174 * enum type. Two enum constants e1 and e2 are of the
175 * same enum type if and only if
176 * e1.getDeclaringClass() == e2.getDeclaringClass().
177 * (The value returned by this method may differ from the one returned
178 * by the {@link Object#getClass} method for enum constants with
179 * constant-specific class bodies.)
180 *
181 * @return the Class object corresponding to this enum constant's
182 * enum type
183 */
184 public final Class<E> getDeclaringClass() {
185 Class clazz = getClass();
186 Class zuper = clazz.getSuperclass();
187 return (zuper == Enum.class) ? clazz : zuper;
188 }
189
190 /**
191 * Returns the enum constant of the specified enum type with the
192 * specified name. The name must match exactly an identifier used
193 * to declare an enum constant in this type. (Extraneous whitespace
194 * characters are not permitted.)
195 *
196 * @param enumType the {@code Class} object of the enum type from which
197 * to return a constant
198 * @param name the name of the constant to return
199 * @return the enum constant of the specified enum type with the
200 * specified name
201 * @throws IllegalArgumentException if the specified enum type has
202 * no constant with the specified name, or the specified
203 * class object does not represent an enum type
204 * @throws NullPointerException if {@code enumType} or {@code name}
205 * is null
206 * @since 1.5
207 */
208 public static <T extends Enum<T>> T valueOf(Class<T> enumType,
209 String name) {
210 T result = enumType.enumConstantDirectory().get(name);
211 if (result != null)
212 return result;
213 if (name == null)
214 throw new NullPointerException("Name is null");
215 throw new IllegalArgumentException("No enum const " + enumType
216 + "." + name);
217 }
218
219 /**
220 * enum classes cannot have finalize methods.
221 */
222 protected final void finalize() {
223 }
224
225 /**
226 * prevent default deserialization
227 */
228 private void readObject(ObjectInputStream in) throws IOException,
229 ClassNotFoundException {
230 throw new InvalidObjectException("can't deserialize enum");
231 }
232
233 private void readObjectNoData() throws ObjectStreamException {
234 throw new InvalidObjectException("can't deserialize enum");
235 }
236 }
|