阅读EnumSet抽象类源码

package java.util;

import sun.misc.sharedsecrets;


public abstract class enumset<e extends enum<e>> extends abstractset<e>
  implements cloneable, java.io.serializable
{
  /**
   * 元素类型
   */
  final class<e> elementtype;

  /**
   * 通过数组存储元素 
   */
  final enum[] universe;

  private static enum[] zero_length_enum_array = new enum[0];

  enumset(class<e>elementtype, enum[] universe) {
    this.elementtype = elementtype;
    this.universe  = universe;
  }

  /**
   * 创造一个空的 enum set 并制定其元素类型
   * @param elementtype the class object of the element type for this enum
   *   set
   * @throws nullpointerexception if <tt>elementtype</tt> is null
   */
  public static <e extends enum<e>> enumset<e> noneof(class<e> elementtype) {
    enum[] universe = getuniverse(elementtype);
    if (universe == null)
      throw new classcastexception(elementtype + " not an enum");

    if (universe.length <= 64)
      return new regularenumset<>(elementtype, universe);
    else
      return new jumboenumset<>(elementtype, universe);
  }

  /**
   * 创建一个包含所有在指定元素类型的元素的枚举set
   *
   * @param elementtype the class object of the element type for this enum
   *   set
   * @throws nullpointerexception if <tt>elementtype</tt> is null
   */
  public static <e extends enum<e>> enumset<e> allof(class<e> elementtype) {
    enumset<e> result = noneof(elementtype);
    result.addall();
    return result;
  }

  /**
   * adds all of the elements from the appropriate enum type to this enum
   * set, which is empty prior to the call.
   */
  abstract void addall();

  /**
   * 创建一个枚举设置相同的元素类型与指定枚举set
   *
   * @param s the enum set from which to initialize this enum set
   * @throws nullpointerexception if <tt>s</tt> is null
   */
  public static <e extends enum<e>> enumset<e> copyof(enumset<e> s) {
    return s.clone();
  }

  /**
   * 创建一个枚举集从指定集合初始化，最初包含相同的元素 
   * @param c the collection from which to initialize this enum set
   * @throws illegalargumentexception if <tt>c</tt> is not an
   *   <tt>enumset</tt> instance and contains no elements
   * @throws nullpointerexception if <tt>c</tt> is null
   */
  public static <e extends enum<e>> enumset<e> copyof(collection<e> c) {
    if (c instanceof enumset) {
      return ((enumset<e>)c).clone();
    } else {
      if (c.isempty())
        throw new illegalargumentexception("collection is empty");
      iterator<e> i = c.iterator();
      e first = i.next();
      enumset<e> result = enumset.of(first);
      while (i.hasnext())
        result.add(i.next());
      return result;
    }
  }

  /**
   * 创建一个枚举集合，其元素与 s 相同
   * @param s the enum set from whose complement to initialize this enum set
   * @throws nullpointerexception if <tt>s</tt> is null
   */
  public static <e extends enum<e>> enumset<e> complementof(enumset<e> s) {
    enumset<e> result = copyof(s);
    result.complement();
    return result;
  }

  /**
   * 1 个元素枚举集合
   *
   * @param e the element that this set is to contain initially
   * @throws nullpointerexception if <tt>e</tt> is null
   * @return an enum set initially containing the specified element
   */
  public static <e extends enum<e>> enumset<e> of(e e) {
    enumset<e> result = noneof(e.getdeclaringclass());
    result.add(e);
    return result;
  }

  /**
   * 2 个元素枚举集合
   *
   * @param e1 an element that this set is to contain initially
   * @param e2 another element that this set is to contain initially
   * @throws nullpointerexception if any parameters are null
   * @return an enum set initially containing the specified elements
   */
  public static <e extends enum<e>> enumset<e> of(e e1, e e2) {
    enumset<e> result = noneof(e1.getdeclaringclass());
    result.add(e1);
    result.add(e2);
    return result;
  }

  /**
   * 3 个元素枚举集合
   *
   * @param e1 an element that this set is to contain initially
   * @param e2 another element that this set is to contain initially
   * @param e3 another element that this set is to contain initially
   * @throws nullpointerexception if any parameters are null
   * @return an enum set initially containing the specified elements
   */
  public static <e extends enum<e>> enumset<e> of(e e1, e e2, e e3) {
    enumset<e> result = noneof(e1.getdeclaringclass());
    result.add(e1);
    result.add(e2);
    result.add(e3);
    return result;
  }

  /**
   * 4 个元素枚举集合
   * @param e1 an element that this set is to contain initially
   * @param e2 another element that this set is to contain initially
   * @param e3 another element that this set is to contain initially
   * @param e4 another element that this set is to contain initially
   * @throws nullpointerexception if any parameters are null
   * @return an enum set initially containing the specified elements
   */
  public static <e extends enum<e>> enumset<e> of(e e1, e e2, e e3, e e4) {
    enumset<e> result = noneof(e1.getdeclaringclass());
    result.add(e1);
    result.add(e2);
    result.add(e3);
    result.add(e4);
    return result;
  }

  /**
   * 5 个元素枚举集合
   *
   * @param e1 an element that this set is to contain initially
   * @param e2 another element that this set is to contain initially
   * @param e3 another element that this set is to contain initially
   * @param e4 another element that this set is to contain initially
   * @param e5 another element that this set is to contain initially
   * @throws nullpointerexception if any parameters are null
   * @return an enum set initially containing the specified elements
   */
  public static <e extends enum<e>> enumset<e> of(e e1, e e2, e e3, e e4,
                          e e5)
  {
    enumset<e> result = noneof(e1.getdeclaringclass());
    result.add(e1);
    result.add(e2);
    result.add(e3);
    result.add(e4);
    result.add(e5);
    return result;
  }

  /**
   * n 个元素枚举集合
   *
   * @param first an element that the set is to contain initially
   * @param rest the remaining elements the set is to contain initially
   * @throws nullpointerexception if any of the specified elements are null,
   *   or if <tt>rest</tt> is null
   * @return an enum set initially containing the specified elements
   */
  @safevarargs
  public static <e extends enum<e>> enumset<e> of(e first, e... rest) {
    enumset<e> result = noneof(first.getdeclaringclass());
    result.add(first);
    for (e e : rest)
      result.add(e);
    return result;
  }

  /**
   * 区间内元素的 枚举集合
   *
   * @param from the first element in the range
   * @param to the last element in the range
   * @throws nullpointerexception if {@code from} or {@code to} are null
   * @throws illegalargumentexception if {@code from.compareto(to) > 0}
   * @return an enum set initially containing all of the elements in the
   *     range defined by the two specified endpoints
   */
  public static <e extends enum<e>> enumset<e> range(e from, e to) {
    if (from.compareto(to) > 0)
      throw new illegalargumentexception(from + " > " + to);
    enumset<e> result = noneof(from.getdeclaringclass());
    result.addrange(from, to);
    return result;
  }

  /**
   * adds the specified range to this enum set, which is empty prior
   * to the call.
   */
  abstract void addrange(e from, e to);

  /**
   * returns a copy of this set.
   *
   * @return a copy of this set
   */
  public enumset<e> clone() {
    try {
      return (enumset<e>) super.clone();
    } catch(clonenotsupportedexception e) {
      throw new assertionerror(e);
    }
  }

  /**
   * complements the contents of this enum set.
   */
  abstract void complement();

  /**
   * throws an exception if e is not of the correct type for this enum set.
   */
  final void typecheck(e e) {
    class eclass = e.getclass();
    if (eclass != elementtype && eclass.getsuperclass() != elementtype)
      throw new classcastexception(eclass + " != " + elementtype);
  }

  /**
   * returns all of the values comprising e.
   * the result is uncloned, cached, and shared by all callers.
   */
  private static <e extends enum<e>> e[] getuniverse(class<e> elementtype) {
    return sharedsecrets.getjavalangaccess()
                    .getenumconstantsshared(elementtype);
  }

  /**
   * this class is used to serialize all enumset instances, regardless of
   * implementation type. it captures their "logical contents" and they
   * are reconstructed using public static factories. this is necessary
   * to ensure that the existence of a particular implementation type is
   * an implementation detail.
   *
   * @serial include
   */
  private static class serializationproxy <e extends enum<e>>
    implements java.io.serializable
  {
    /**
     * the element type of this enum set.
     *
     * @serial
     */
    private final class<e> elementtype;

    /**
     * the elements contained in this enum set.
     *
     * @serial
     */
    private final enum[] elements;

    serializationproxy(enumset<e> set) {
      elementtype = set.elementtype;
      elements = set.toarray(zero_length_enum_array);
    }

    private object readresolve() {
      enumset<e> result = enumset.noneof(elementtype);
      for (enum e : elements)
        result.add((e)e);
      return result;
    }

    private static final long serialversionuid = 362491234563181265l;
  }

  object writereplace() {
    return new serializationproxy<>(this);
  }

  // readobject method for the serialization proxy pattern
  // see effective java, second ed., item 78.
  private void readobject(java.io.objectinputstream stream)
    throws java.io.invalidobjectexception {
    throw new java.io.invalidobjectexception("proxy required");
  }
}