EnumSet.java

/*
 * Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.util;

import java.io.InvalidObjectException;
import java.io.ObjectInputStream;
import java.io.Serializable;
import jdk.internal.misc.SharedSecrets;

/**
 * A specialized {@link Set} implementation for use with enum types.  All of
 * the elements in an enum set must come from a single enum type that is
 * specified, explicitly or implicitly, when the set is created.  Enum sets
 * are represented internally as bit vectors.  This representation is
 * extremely compact and efficient. The space and time performance of this
 * class should be good enough to allow its use as a high-quality, typesafe
 * alternative to traditional {@code int}-based "bit flags."  Even bulk
 * operations (such as {@code containsAll} and {@code retainAll}) should
 * run very quickly if their argument is also an enum set.
 *
 * <p>The iterator returned by the {@code iterator} method traverses the
 * elements in their <i>natural order</i> (the order in which the enum
 * constants are declared).  The returned iterator is <i>weakly
 * consistent</i>: it will never throw {@link ConcurrentModificationException}
 * and it may or may not show the effects of any modifications to the set that
 * occur while the iteration is in progress.
 *
 * <p>Null elements are not permitted.  Attempts to insert a null element
 * will throw {@link NullPointerException}.  Attempts to test for the
 * presence of a null element or to remove one will, however, function
 * properly.
 *
 * <P>Like most collection implementations, {@code EnumSet} is not
 * synchronized.  If multiple threads access an enum set concurrently, and at
 * least one of the threads modifies the set, it should be synchronized
 * externally.  This is typically accomplished by synchronizing on some
 * object that naturally encapsulates the enum set.  If no such object exists,
 * the set should be "wrapped" using the {@link Collections#synchronizedSet}
 * method.  This is best done at creation time, to prevent accidental
 * unsynchronized access:
 *
 * <pre>
 * Set&lt;MyEnum&gt; s = Collections.synchronizedSet(EnumSet.noneOf(MyEnum.class));
 * </pre>
 *
 * <p>Implementation note: All basic operations execute in constant time.
 * They are likely (though not guaranteed) to be much faster than their
 * {@link HashSet} counterparts.  Even bulk operations execute in
 * constant time if their argument is also an enum set.
 *
 * <p>This class is a member of the
 * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
 * Java Collections Framework</a>.
 *
 * @author Josh Bloch
 * @see EnumMap
 * @since 1.5
 */
// 枚举集合，要求集合元素必须限定为指定枚举类型中的(常量)实例
@SuppressWarnings("serial") // No serialVersionUID due to usage of
public abstract class EnumSet<E extends Enum<E>> extends AbstractSet<E> implements Cloneable, Serializable {
    
    /**
     * The class of all the elements of this set.
     */
    final transient Class<E> elementType;   // 当前集合中的元素类型（枚举类型）
    
    /**
     * All of the values comprising E.  (Cached for performance.)
     */
    final transient Enum<?>[] universe;     // 缓存所有可能存储的枚举实例
    
    EnumSet(Class<E> elementType, Enum<?>[] universe) {
        this.elementType = elementType;
        this.universe = universe;
    }
    
    /**
     * Adds all of the elements from the appropriate enum type to this enum set, which is empty prior to the call.
     */
    // 将所有枚举实例添加到当前枚举集合中（universe指示了所有枚举实例）
    abstract void addAll();
    
    /**
     * Adds the specified range to this enum set, which is empty prior to the call.
     */
    // 向当前枚举集合中添加指定范围内的枚举实例
    abstract void addRange(E from, E to);
    
    /**
     * Complements the contents of this enum set.
     */
    // 获取当前枚举集合的补集
    abstract void complement();
    
    /**
     * Creates an empty enum set with the specified element type.
     *
     * @param <E> The class of the elements in the set
     * @param elementType the class object of the element type for this enum set
     * @return An empty enum set of the specified type.
     * @throws NullPointerException if {@code elementType} is null
     */
    // 返回一个空的枚举集合，其元素类型为elementType
    public static <E extends Enum<E>> EnumSet<E> noneOf(Class<E> elementType) {
        // 获取枚举类型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);
        }
    }
    
    /**
     * Creates an enum set containing all of the elements in the specified element type.
     *
     * @param <E> The class of the elements in the set
     * @param elementType the class object of the element type for this enum set
     * @return An enum set containing all the elements in the specified type.
     * @throws NullPointerException if {@code elementType} is null
     */
    // 返回一个包含了所有枚举实例的枚举集合（universe指示了所有枚举实例）
    public static <E extends Enum<E>> EnumSet<E> allOf(Class<E> elementType) {
        // 返回一个枚举集合，其元素类型为elementType
        EnumSet<E> result = noneOf(elementType);
        // 将所有枚举实例添加到当前枚举集合中（universe指示了所有枚举实例）
        result.addAll();
        return result;
    }
    
    /**
     * Creates an enum set initially containing all of the elements in the
     * range defined by the two specified endpoints.  The returned set will
     * contain the endpoints themselves, which may be identical but must not
     * be out of order.
     *
     * @param <E> The class of the parameter elements and of the set
     * @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);
        }
        
        // 获取枚举类类对象
        Class<E> elementType = from.getDeclaringClass();
        
        // 返回一个空的枚举集合，其元素类型为elementType
        EnumSet<E> result = noneOf(elementType);
        
        // 向当前枚举集合中添加指定范围内的枚举实例
        result.addRange(from, to);
        
        return result;
    }
    
    /**
     * Creates an enum set with the same element type as the specified enum
     * set, initially containing all the elements of this type that are
     * <i>not</i> contained in the specified set.
     *
     * @param <E> The class of the elements in the enum set
     * @param s the enum set from whose complement to initialize this enum set
     * @return The complement of the specified set in this set
     * @throws NullPointerException if {@code s} is null
     */
    // 获取当前枚举集合的补集
    public static <E extends Enum<E>> EnumSet<E> complementOf(EnumSet<E> s) {
        EnumSet<E> result = copyOf(s);
        result.complement();
        return result;
    }
    
    /**
     * Creates an enum set with the same element type as the specified enum set,
     * initially containing the same elements (if any).
     *
     * @param <E> The class of the elements in the set
     * @param s the enum set from which to initialize this enum set
     * @return A copy of the specified enum set.
     * @throws NullPointerException if {@code s} is null
     */
    // 返回当前枚举集合的一个克隆
    public static <E extends Enum<E>> EnumSet<E> copyOf(EnumSet<E> s) {
        return s.clone();
    }
    
    /**
     * Creates an enum set initialized from the specified collection.  If
     * the specified collection is an {@code EnumSet} instance, this static
     * factory method behaves identically to {@link #copyOf(EnumSet)}.
     * Otherwise, the specified collection must contain at least one element
     * (in order to determine the new enum set's element type).
     *
     * @param <E> The class of the elements in the collection
     * @param c the collection from which to initialize this enum set
     * @return An enum set initialized from the given collection.
     * @throws IllegalArgumentException if {@code c} is not an
     *     {@code EnumSet} instance and contains no elements
     * @throws NullPointerException if {@code c} 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> iterator = c.iterator();
            
            E first = iterator.next();
            EnumSet<E> result = EnumSet.of(first);
            
            while(iterator.hasNext()) {
                result.add(iterator.next());
            }
            
            
            return result;
        }
    }
    
    /**
     * Creates an enum set initially containing the specified element.
     *
     * Overloadings of this method exist to initialize an enum set with
     * one through five elements.  A sixth overloading is provided that
     * uses the varargs feature.  This overloading may be used to create
     * an enum set initially containing an arbitrary number of elements, but
     * is likely to run slower than the overloadings that do not use varargs.
     *
     * @param <E> The class of the specified element and of the set
     * @param e the element that this set is to contain initially
     * @throws NullPointerException if {@code e} is null
     * @return an enum set initially containing the specified element
     */
    // 返回包含了指定元素的枚举集合
    public static <E extends Enum<E>> EnumSet<E> of(E e) {
        // 获取枚举类类对象
        Class<E> elementType = e.getDeclaringClass();
        
        // 返回一个空的枚举集合，其元素类型为elementType
        EnumSet<E> result = noneOf(elementType);
        
        // 向当前容器中添加元素
        result.add(e);
        
        return result;
    }
    
    /**
     * Creates an enum set initially containing the specified elements.
     *
     * Overloadings of this method exist to initialize an enum set with
     * one through five elements.  A sixth overloading is provided that
     * uses the varargs feature.  This overloading may be used to create
     * an enum set initially containing an arbitrary number of elements, but
     * is likely to run slower than the overloadings that do not use varargs.
     *
     * @param <E> The class of the parameter elements and of the set
     * @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) {
        // 获取枚举类类对象
        Class<E> elementType = e1.getDeclaringClass();
        
        // 返回一个空的枚举集合，其元素类型为elementType
        EnumSet<E> result = noneOf(elementType);
        
        // 向当前容器中添加元素
        result.add(e1);
        result.add(e2);
        
        return result;
    }
    
    /**
     * Creates an enum set initially containing the specified elements.
     *
     * Overloadings of this method exist to initialize an enum set with
     * one through five elements.  A sixth overloading is provided that
     * uses the varargs feature.  This overloading may be used to create
     * an enum set initially containing an arbitrary number of elements, but
     * is likely to run slower than the overloadings that do not use varargs.
     *
     * @param <E> The class of the parameter elements and of the set
     * @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) {
        // 获取枚举类类对象
        Class<E> elementType = e1.getDeclaringClass();
        
        // 返回一个空的枚举集合，其元素类型为elementType
        EnumSet<E> result = noneOf(elementType);
        
        // 向当前容器中添加元素
        result.add(e1);
        result.add(e2);
        result.add(e3);
        
        return result;
    }
    
    /**
     * Creates an enum set initially containing the specified elements.
     *
     * Overloadings of this method exist to initialize an enum set with
     * one through five elements.  A sixth overloading is provided that
     * uses the varargs feature.  This overloading may be used to create
     * an enum set initially containing an arbitrary number of elements, but
     * is likely to run slower than the overloadings that do not use varargs.
     *
     * @param <E> The class of the parameter elements and of the set
     * @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) {
        // 获取枚举类类对象
        Class<E> elementType = e1.getDeclaringClass();
        
        // 返回一个空的枚举集合，其元素类型为elementType
        EnumSet<E> result = noneOf(elementType);
        
        // 向当前容器中添加元素
        result.add(e1);
        result.add(e2);
        result.add(e3);
        result.add(e4);
        
        return result;
    }
    
    /**
     * Creates an enum set initially containing the specified elements.
     *
     * Overloadings of this method exist to initialize an enum set with
     * one through five elements.  A sixth overloading is provided that
     * uses the varargs feature.  This overloading may be used to create
     * an enum set initially containing an arbitrary number of elements, but
     * is likely to run slower than the overloadings that do not use varargs.
     *
     * @param <E> The class of the parameter elements and of the set
     * @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) {
        // 获取枚举类类对象
        Class<E> elementType = e1.getDeclaringClass();
        
        // 返回一个空的枚举集合，其元素类型为elementType
        EnumSet<E> result = noneOf(elementType);
        
        // 向当前容器中添加元素
        result.add(e1);
        result.add(e2);
        result.add(e3);
        result.add(e4);
        result.add(e5);
        
        return result;
    }
    
    /**
     * Creates an enum set initially containing the specified elements.
     * This factory, whose parameter list uses the varargs feature, may
     * be used to create an enum set initially containing an arbitrary
     * number of elements, but it is likely to run slower than the overloadings
     * that do not use varargs.
     *
     * @param <E> The class of the parameter elements and of the set
     * @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 {@code rest} 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) {
        // 获取枚举类类对象
        Class<E> elementType = first.getDeclaringClass();
        
        // 返回一个空的枚举集合，其元素类型为elementType
        EnumSet<E> result = noneOf(elementType);
        
        // 向当前容器中添加元素
        result.add(first);
        Collections.addAll(result, rest);
        
        return result;
    }
    
    /**
     * 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.
     */
    // 获取枚举类型elementType中包含的枚举常量
    private static <E extends Enum<E>> E[] getUniverse(Class<E> elementType) {
        return SharedSecrets.getJavaLangAccess().getEnumConstantsShared(elementType);
    }
    
    /**
     * Returns a copy of this set.
     *
     * @return a copy of this set
     */
    @SuppressWarnings("unchecked")
    public EnumSet<E> clone() {
        try {
            return (EnumSet<E>) super.clone();
        } catch(CloneNotSupportedException e) {
            throw new AssertionError(e);
        }
    }
    
    /**
     * Returns a
     * <a href="../../serialized-form.html#java.util.EnumSet.SerializationProxy">
     * SerializationProxy</a>
     * representing the state of this instance.
     *
     * @return a {@link SerializationProxy}
     * representing the state of this instance
     */
    Object writeReplace() {
        return new SerializationProxy<>(this);
    }
    
    /**
     * @param s the stream
     *
     * @throws java.io.InvalidObjectException always
     */
    private void readObject(ObjectInputStream s) throws InvalidObjectException {
        throw new InvalidObjectException("Proxy required");
    }
    
    
    
    /**
     * 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 Serializable {
        private static final long serialVersionUID = 362491234563181265L;
        
        private static final Enum<?>[] ZERO_LENGTH_ENUM_ARRAY = new Enum<?>[0];
        
        /**
         * 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);
        }
        
        /**
         * Returns an {@code EnumSet} object with initial state
         * held by this proxy.
         *
         * @return a {@code EnumSet} object with initial state
         * held by this proxy
         */
        @SuppressWarnings("unchecked")
        private Object readResolve() {
            // instead of cast to E, we should perhaps use elementType.cast() to avoid injection of forged stream,
            // but it will slow the implementation
            EnumSet<E> result = EnumSet.noneOf(elementType);
            for(Enum<?> e : elements) {
                result.add((E) e);
            }
            return result;
        }
    }
    
}