Java枚举

package java.lang;

import java.io.Serializable;
import java.io.IOException;
import java.io.InvalidObjectException;
import java.io.ObjectInputStream;
import java.io.ObjectStreamException;

/**
 * 这是所有java语言枚举类型的公共基类。 
 *
 *
 * 注意，当使用枚举类型作为集合的类型时或者作为地图中键的类型，专门且高效
 * {@linkplain java.util.EnumSet set} 和{@linkplain
 * java.util.EnumMap map} 可以实现。
 *
 * @param <E>枚举类型的子类
 * @author  Josh Bloch
 * @author  Neal Gafter
 * @see     Class#getEnumConstants()
 * @see     java.util.EnumSet
 * @see     java.util.EnumMap
 * @since   1.5
 */
public abstract class Enum<E extends Enum<E>>
        implements Comparable<E>, Serializable {
    /**
     * 枚举常量的名称，在其枚举声明中对其进行声明。
     * 大多数程序员应该使用 {@link #toString} 方法而不是直接访问此字段。
     */
    private final String name;

    /**
     * 返回此枚举常量的名称，在其枚举声明中对其进行声明。
     *
     * 与此方法相比，大多数程序员应该优先考虑使用 toString() 方法，因为 toString 方法返回更加用户友好的名称。
     * 该方法主要设计用于特殊情形，其正确性取决于获取正确的名称，其名称不会随版本的改变而改变。
     *
     * @return 返回此枚举常量的名称。
     */
    public final String name() {
        return name;
    }

    /**
     * 枚举常量的序数（它在枚举声明中的位置，其中初始常量序数为零）。
     *
     * 大多数程序员不会使用此变量。它被设计用于复杂的基于枚举的数据结构，比如 
     * {@link java.util.EnumSet} 和 {@link java.util.EnumMap}。
     */
    private final int ordinal;


    /**
     * 返回枚举常量的序数（它在枚举声明中的位置，其中初始常量序数为零）。
     *
     * 大多数程序员不会使用此方法。它被设计用于复杂的基于枚举的数据结构，比如 
     * {@link java.util.EnumSet} 和 {@link java.util.EnumMap}。
     */
    public final int ordinal() {
        return ordinal;
    }

    /**
     * 唯一的构造函数。程序员不能调用这个构造函数。它是利用由响应枚举类型声明编译器产生的代码。
     * @param name - 此枚举常量的名称，它是用来声明该常量的标识符。
     * @param ordinal - 枚举常量的序数（它在枚举声明中的位置，其中初始常量序数为零）。
     */
    protected Enum(String name, int ordinal) {
        this.name = name;
        this.ordinal = ordinal;
    }

    /**
     * 返回枚举常量的名称，它包含在声明中。可以重写此方法，虽然一般来说没有必要。当存在更加“程序员友好的”字符串形式时，应该使用枚举类型重写此方法。
     * 覆盖类 Object 中的 toString 
     * 
     * @return  枚举常量的名称 
     */
    public String toString() {
        return name;
    }

    /**
     * 当指定对象等于此枚举常量时，返回 true。
     * 覆盖类 Object 中的 equals 
     * 
     * @param other 要与此对象进行相等性比较的对象。
     * @return   如果指定对象等于此枚举常量，则返回 true。
     */
    public final boolean equals(Object other) {
        return this==other;
    }

    /**
     * 返回枚举常量的哈希码。
     * 覆盖类 Object 中的 hashCode 
     *
     * @return 枚举常量的哈希码。
     */
    public final int hashCode() {
        return super.hashCode();
    }

    /**
     * 抛出 CloneNotSupportedException。这可保证永远不会复制枚举，以保证枚举是单例的。
     * 覆盖类 Object 中的clone
     * 
     * @return (不返回)
     */
    protected final Object clone() throws CloneNotSupportedException {
        throw new CloneNotSupportedException();
    }

    /**
     * 比较此枚举与指定对象的顺序。在该对象小于、等于或大于指定对象时，分别返回负整数、零或正整数。 
     * 枚举常量只能与相同枚举类型的其他枚举常量进行比较。该方法实现的自然顺序就是声明常量的顺序。 
     *
     *
     */
    public final int compareTo(E o) {
        Enum<?> other = (Enum<?>)o;
        Enum<E> self = this;
        if (self.getClass() != other.getClass() && // optimization
            self.getDeclaringClass() != other.getDeclaringClass())
            throw new ClassCastException();
        return self.ordinal - other.ordinal;
    }

    /**
     * 返回与此枚举常量的枚举类型相对应的 Class 对象。当且仅当 e1.getDeclaringClass() == e2.getDeclaringClass() 时，
     * 两个枚举常量 e1 和 e2 的枚举类型才相同。（由该方法返回的值不同于由 Object.getClass() 方法返回的值， Object.getClass() 
     * 方法用于带有特定常量的类主体的枚举常量。） 
     *
     * @return 与此枚举常量的枚举类型相对应的 Class 对象 
     */
    @SuppressWarnings("unchecked")
    public final Class<E> getDeclaringClass() {
        Class<?> clazz = getClass();
        Class<?> zuper = clazz.getSuperclass();
        return (zuper == Enum.class) ? (Class<E>)clazz : (Class<E>)zuper;
    }

    /**
     * 返回带指定名称的指定枚举类型的枚举常量。名称必须与在此类型中声明枚举常量所用的标识符完全匹配（不允许使用额外的空白字符）。
     * 
     * @param 要从中返回常量的枚举类型的 Class 对象 
     * @param 要返回的常量名称
     * @return 带指定名称的指定枚举类型的枚举常量 
     * @throws IllegalArgumentException  如果指定枚举类型不包含指定名称的常量，或者指定类对象不表示枚举类型 
     * @throws 如果 enumType 或 name 为空 
     * @since 1.5
     */
    public static <T extends Enum<T>> T valueOf(Class<T> enumType,
                                                String name) {
        T result = enumType.enumConstantDirectory().get(name);
        if (result != null)
            return result;
        if (name == null)
            throw new NullPointerException("Name is null");
        throw new IllegalArgumentException(
            "No enum constant " + enumType.getCanonicalName() + "." + name);
    }

    /**
     * 枚举类不能有 finalize 方法。 
     * 覆盖类 Object 中的 finalize。

     */
    protected final void finalize() { }

    /**
     * 禁止反序列化
     */
    private void readObject(ObjectInputStream in) throws IOException,
        ClassNotFoundException {
        throw new InvalidObjectException("can‘t deserialize enum");
    }

    private void readObjectNoData() throws ObjectStreamException {
        throw new InvalidObjectException("can‘t deserialize enum");
    }
}