1 /*
2  * Copyright (C) 2014 The Android Open Source Project
3  * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5  *
6  * This code is free software; you can redistribute it and/or modify it
7  * under the terms of the GNU General Public License version 2 only, as
8  * published by the Free Software Foundation.  Oracle designates this
9  * particular file as subject to the "Classpath" exception as provided
10  * by Oracle in the LICENSE file that accompanied this code.
11  *
12  * This code is distributed in the hope that it will be useful, but WITHOUT
13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
15  * version 2 for more details (a copy is included in the LICENSE file that
16  * accompanied this code).
17  *
18  * You should have received a copy of the GNU General Public License version
19  * 2 along with this work; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
21  *
22  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
23  * or visit www.oracle.com if you need additional information or have any
24  * questions.
25  */
26 
27 package java.util;
28 
29 /**
30  * A specialized {@link Set} implementation for use with enum types.  All of
31  * the elements in an enum set must come from a single enum type that is
32  * specified, explicitly or implicitly, when the set is created.  Enum sets
33  * are represented internally as bit vectors.  This representation is
34  * extremely compact and efficient. The space and time performance of this
35  * class should be good enough to allow its use as a high-quality, typesafe
36  * alternative to traditional <tt>int</tt>-based "bit flags."  Even bulk
37  * operations (such as <tt>containsAll</tt> and <tt>retainAll</tt>) should
38  * run very quickly if their argument is also an enum set.
39  *
40  * <p>The iterator returned by the <tt>iterator</tt> method traverses the
41  * elements in their <i>natural order</i> (the order in which the enum
42  * constants are declared).  The returned iterator is <i>weakly
43  * consistent</i>: it will never throw {@link ConcurrentModificationException}
44  * and it may or may not show the effects of any modifications to the set that
45  * occur while the iteration is in progress.
46  *
47  * <p>Null elements are not permitted.  Attempts to insert a null element
48  * will throw {@link NullPointerException}.  Attempts to test for the
49  * presence of a null element or to remove one will, however, function
50  * properly.
51  *
52  * <P>Like most collection implementations, <tt>EnumSet</tt> is not
53  * synchronized.  If multiple threads access an enum set concurrently, and at
54  * least one of the threads modifies the set, it should be synchronized
55  * externally.  This is typically accomplished by synchronizing on some
56  * object that naturally encapsulates the enum set.  If no such object exists,
57  * the set should be "wrapped" using the {@link Collections#synchronizedSet}
58  * method.  This is best done at creation time, to prevent accidental
59  * unsynchronized access:
60  *
61  * <pre>
62  * Set&lt;MyEnum&gt; s = Collections.synchronizedSet(EnumSet.noneOf(MyEnum.class));
63  * </pre>
64  *
65  * <p>Implementation note: All basic operations execute in constant time.
66  * They are likely (though not guaranteed) to be much faster than their
67  * {@link HashSet} counterparts.  Even bulk operations execute in
68  * constant time if their argument is also an enum set.
69  *
70  * <p>This class is a member of the
71  * <a href="{@docRoot}openjdk-redirect.html?v=8&path=/technotes/guides/collections/index.html">
72  * Java Collections Framework</a>.
73  *
74  * @author Josh Bloch
75  * @since 1.5
76  * @see EnumMap
77  * @serial exclude
78  */
79 public abstract class EnumSet<E extends Enum<E>> extends AbstractSet<E>
80     implements Cloneable, java.io.Serializable
81 {
82     /**
83      * The class of all the elements of this set.
84      */
85     final Class<E> elementType;
86 
87     /**
88      * All of the values comprising T.  (Cached for performance.)
89      */
90     final Enum<?>[] universe;
91 
92     private static Enum<?>[] ZERO_LENGTH_ENUM_ARRAY = new Enum<?>[0];
93 
EnumSet(Class<E>elementType, Enum<?>[] universe)94     EnumSet(Class<E>elementType, Enum<?>[] universe) {
95         this.elementType = elementType;
96         this.universe    = universe;
97     }
98 
99     /**
100      * Creates an empty enum set with the specified element type.
101      *
102      * @param <E> The class of the elements in the set
103      * @param elementType the class object of the element type for this enum
104      *     set
105      * @return An empty enum set of the specified type.
106      * @throws NullPointerException if <tt>elementType</tt> is null
107      */
noneOf(Class<E> elementType)108     public static <E extends Enum<E>> EnumSet<E> noneOf(Class<E> elementType) {
109         Enum<?>[] universe = getUniverse(elementType);
110         if (universe == null)
111             throw new ClassCastException(elementType + " not an enum");
112 
113         if (universe.length <= 64)
114             return new RegularEnumSet<>(elementType, universe);
115         else
116             return new JumboEnumSet<>(elementType, universe);
117     }
118 
119     /**
120      * Creates an enum set containing all of the elements in the specified
121      * element type.
122      *
123      * @param <E> The class of the elements in the set
124      * @param elementType the class object of the element type for this enum
125      *     set
126      * @return An enum set containing all the elements in the specified type.
127      * @throws NullPointerException if <tt>elementType</tt> is null
128      */
allOf(Class<E> elementType)129     public static <E extends Enum<E>> EnumSet<E> allOf(Class<E> elementType) {
130         EnumSet<E> result = noneOf(elementType);
131         result.addAll();
132         return result;
133     }
134 
135     /**
136      * Adds all of the elements from the appropriate enum type to this enum
137      * set, which is empty prior to the call.
138      */
addAll()139     abstract void addAll();
140 
141     /**
142      * Creates an enum set with the same element type as the specified enum
143      * set, initially containing the same elements (if any).
144      *
145      * @param <E> The class of the elements in the set
146      * @param s the enum set from which to initialize this enum set
147      * @return A copy of the specified enum set.
148      * @throws NullPointerException if <tt>s</tt> is null
149      */
copyOf(EnumSet<E> s)150     public static <E extends Enum<E>> EnumSet<E> copyOf(EnumSet<E> s) {
151         return s.clone();
152     }
153 
154     /**
155      * Creates an enum set initialized from the specified collection.  If
156      * the specified collection is an <tt>EnumSet</tt> instance, this static
157      * factory method behaves identically to {@link #copyOf(EnumSet)}.
158      * Otherwise, the specified collection must contain at least one element
159      * (in order to determine the new enum set's element type).
160      *
161      * @param <E> The class of the elements in the collection
162      * @param c the collection from which to initialize this enum set
163      * @return An enum set initialized from the given collection.
164      * @throws IllegalArgumentException if <tt>c</tt> is not an
165      *     <tt>EnumSet</tt> instance and contains no elements
166      * @throws NullPointerException if <tt>c</tt> is null
167      */
copyOf(Collection<E> c)168     public static <E extends Enum<E>> EnumSet<E> copyOf(Collection<E> c) {
169         if (c instanceof EnumSet) {
170             return ((EnumSet<E>)c).clone();
171         } else {
172             if (c.isEmpty())
173                 throw new IllegalArgumentException("Collection is empty");
174             Iterator<E> i = c.iterator();
175             E first = i.next();
176             EnumSet<E> result = EnumSet.of(first);
177             while (i.hasNext())
178                 result.add(i.next());
179             return result;
180         }
181     }
182 
183     /**
184      * Creates an enum set with the same element type as the specified enum
185      * set, initially containing all the elements of this type that are
186      * <i>not</i> contained in the specified set.
187      *
188      * @param <E> The class of the elements in the enum set
189      * @param s the enum set from whose complement to initialize this enum set
190      * @return The complement of the specified set in this set
191      * @throws NullPointerException if <tt>s</tt> is null
192      */
complementOf(EnumSet<E> s)193     public static <E extends Enum<E>> EnumSet<E> complementOf(EnumSet<E> s) {
194         EnumSet<E> result = copyOf(s);
195         result.complement();
196         return result;
197     }
198 
199     /**
200      * Creates an enum set initially containing the specified element.
201      *
202      * Overloadings of this method exist to initialize an enum set with
203      * one through five elements.  A sixth overloading is provided that
204      * uses the varargs feature.  This overloading may be used to create
205      * an enum set initially containing an arbitrary number of elements, but
206      * is likely to run slower than the overloadings that do not use varargs.
207      *
208      * @param <E> The class of the specified element and of the set
209      * @param e the element that this set is to contain initially
210      * @throws NullPointerException if <tt>e</tt> is null
211      * @return an enum set initially containing the specified element
212      */
of(E e)213     public static <E extends Enum<E>> EnumSet<E> of(E e) {
214         EnumSet<E> result = noneOf(e.getDeclaringClass());
215         result.add(e);
216         return result;
217     }
218 
219     /**
220      * Creates an enum set initially containing the specified elements.
221      *
222      * Overloadings of this method exist to initialize an enum set with
223      * one through five elements.  A sixth overloading is provided that
224      * uses the varargs feature.  This overloading may be used to create
225      * an enum set initially containing an arbitrary number of elements, but
226      * is likely to run slower than the overloadings that do not use varargs.
227      *
228      * @param <E> The class of the parameter elements and of the set
229      * @param e1 an element that this set is to contain initially
230      * @param e2 another element that this set is to contain initially
231      * @throws NullPointerException if any parameters are null
232      * @return an enum set initially containing the specified elements
233      */
of(E e1, E e2)234     public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2) {
235         EnumSet<E> result = noneOf(e1.getDeclaringClass());
236         result.add(e1);
237         result.add(e2);
238         return result;
239     }
240 
241     /**
242      * Creates an enum set initially containing the specified elements.
243      *
244      * Overloadings of this method exist to initialize an enum set with
245      * one through five elements.  A sixth overloading is provided that
246      * uses the varargs feature.  This overloading may be used to create
247      * an enum set initially containing an arbitrary number of elements, but
248      * is likely to run slower than the overloadings that do not use varargs.
249      *
250      * @param <E> The class of the parameter elements and of the set
251      * @param e1 an element that this set is to contain initially
252      * @param e2 another element that this set is to contain initially
253      * @param e3 another element that this set is to contain initially
254      * @throws NullPointerException if any parameters are null
255      * @return an enum set initially containing the specified elements
256      */
of(E e1, E e2, E e3)257     public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3) {
258         EnumSet<E> result = noneOf(e1.getDeclaringClass());
259         result.add(e1);
260         result.add(e2);
261         result.add(e3);
262         return result;
263     }
264 
265     /**
266      * Creates an enum set initially containing the specified elements.
267      *
268      * Overloadings of this method exist to initialize an enum set with
269      * one through five elements.  A sixth overloading is provided that
270      * uses the varargs feature.  This overloading may be used to create
271      * an enum set initially containing an arbitrary number of elements, but
272      * is likely to run slower than the overloadings that do not use varargs.
273      *
274      * @param <E> The class of the parameter elements and of the set
275      * @param e1 an element that this set is to contain initially
276      * @param e2 another element that this set is to contain initially
277      * @param e3 another element that this set is to contain initially
278      * @param e4 another element that this set is to contain initially
279      * @throws NullPointerException if any parameters are null
280      * @return an enum set initially containing the specified elements
281      */
of(E e1, E e2, E e3, E e4)282     public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3, E e4) {
283         EnumSet<E> result = noneOf(e1.getDeclaringClass());
284         result.add(e1);
285         result.add(e2);
286         result.add(e3);
287         result.add(e4);
288         return result;
289     }
290 
291     /**
292      * Creates an enum set initially containing the specified elements.
293      *
294      * Overloadings of this method exist to initialize an enum set with
295      * one through five elements.  A sixth overloading is provided that
296      * uses the varargs feature.  This overloading may be used to create
297      * an enum set initially containing an arbitrary number of elements, but
298      * is likely to run slower than the overloadings that do not use varargs.
299      *
300      * @param <E> The class of the parameter elements and of the set
301      * @param e1 an element that this set is to contain initially
302      * @param e2 another element that this set is to contain initially
303      * @param e3 another element that this set is to contain initially
304      * @param e4 another element that this set is to contain initially
305      * @param e5 another element that this set is to contain initially
306      * @throws NullPointerException if any parameters are null
307      * @return an enum set initially containing the specified elements
308      */
of(E e1, E e2, E e3, E e4, E e5)309     public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3, E e4,
310                                                     E e5)
311     {
312         EnumSet<E> result = noneOf(e1.getDeclaringClass());
313         result.add(e1);
314         result.add(e2);
315         result.add(e3);
316         result.add(e4);
317         result.add(e5);
318         return result;
319     }
320 
321     /**
322      * Creates an enum set initially containing the specified elements.
323      * This factory, whose parameter list uses the varargs feature, may
324      * be used to create an enum set initially containing an arbitrary
325      * number of elements, but it is likely to run slower than the overloadings
326      * that do not use varargs.
327      *
328      * @param <E> The class of the parameter elements and of the set
329      * @param first an element that the set is to contain initially
330      * @param rest the remaining elements the set is to contain initially
331      * @throws NullPointerException if any of the specified elements are null,
332      *     or if <tt>rest</tt> is null
333      * @return an enum set initially containing the specified elements
334      */
335     @SafeVarargs
of(E first, E... rest)336     public static <E extends Enum<E>> EnumSet<E> of(E first, E... rest) {
337         EnumSet<E> result = noneOf(first.getDeclaringClass());
338         result.add(first);
339         for (E e : rest)
340             result.add(e);
341         return result;
342     }
343 
344     /**
345      * Creates an enum set initially containing all of the elements in the
346      * range defined by the two specified endpoints.  The returned set will
347      * contain the endpoints themselves, which may be identical but must not
348      * be out of order.
349      *
350      * @param <E> The class of the parameter elements and of the set
351      * @param from the first element in the range
352      * @param to the last element in the range
353      * @throws NullPointerException if {@code from} or {@code to} are null
354      * @throws IllegalArgumentException if {@code from.compareTo(to) > 0}
355      * @return an enum set initially containing all of the elements in the
356      *         range defined by the two specified endpoints
357      */
range(E from, E to)358     public static <E extends Enum<E>> EnumSet<E> range(E from, E to) {
359         if (from.compareTo(to) > 0)
360             throw new IllegalArgumentException(from + " > " + to);
361         EnumSet<E> result = noneOf(from.getDeclaringClass());
362         result.addRange(from, to);
363         return result;
364     }
365 
366     /**
367      * Adds the specified range to this enum set, which is empty prior
368      * to the call.
369      */
addRange(E from, E to)370     abstract void addRange(E from, E to);
371 
372     /**
373      * Returns a copy of this set.
374      *
375      * @return a copy of this set
376      */
377     @SuppressWarnings("unchecked")
clone()378     public EnumSet<E> clone() {
379         try {
380             return (EnumSet<E>) super.clone();
381         } catch(CloneNotSupportedException e) {
382             throw new AssertionError(e);
383         }
384     }
385 
386     /**
387      * Complements the contents of this enum set.
388      */
complement()389     abstract void complement();
390 
391     /**
392      * Throws an exception if e is not of the correct type for this enum set.
393      */
typeCheck(E e)394     final void typeCheck(E e) {
395         Class<?> eClass = e.getClass();
396         if (eClass != elementType && eClass.getSuperclass() != elementType)
397             throw new ClassCastException(eClass + " != " + elementType);
398     }
399 
400     /**
401      * Returns all of the values comprising E.
402      * The result is uncloned, cached, and shared by all callers.
403      */
getUniverse(Class<E> elementType)404     private static <E extends Enum<E>> E[] getUniverse(Class<E> elementType) {
405         // Android-changed: Use JavaLangAccess directly instead of going via
406         // SharedSecrets.
407         return java.lang.JavaLangAccess.getEnumConstantsShared(elementType);
408     }
409 
410     /**
411      * This class is used to serialize all EnumSet instances, regardless of
412      * implementation type.  It captures their "logical contents" and they
413      * are reconstructed using public static factories.  This is necessary
414      * to ensure that the existence of a particular implementation type is
415      * an implementation detail.
416      *
417      * @serial include
418      */
419     private static class SerializationProxy <E extends Enum<E>>
420         implements java.io.Serializable
421     {
422         /**
423          * The element type of this enum set.
424          *
425          * @serial
426          */
427         private final Class<E> elementType;
428 
429         /**
430          * The elements contained in this enum set.
431          *
432          * @serial
433          */
434         private final Enum<?>[] elements;
435 
SerializationProxy(EnumSet<E> set)436         SerializationProxy(EnumSet<E> set) {
437             elementType = set.elementType;
438             elements = set.toArray(ZERO_LENGTH_ENUM_ARRAY);
439         }
440 
441         // instead of cast to E, we should perhaps use elementType.cast()
442         // to avoid injection of forged stream, but it will slow the implementation
443         @SuppressWarnings("unchecked")
readResolve()444         private Object readResolve() {
445             EnumSet<E> result = EnumSet.noneOf(elementType);
446             for (Enum<?> e : elements)
447                 result.add((E)e);
448             return result;
449         }
450 
451         private static final long serialVersionUID = 362491234563181265L;
452     }
453 
writeReplace()454     Object writeReplace() {
455         return new SerializationProxy<>(this);
456     }
457 
458     // readObject method for the serialization proxy pattern
459     // See Effective Java, Second Ed., Item 78.
readObject(java.io.ObjectInputStream stream)460     private void readObject(java.io.ObjectInputStream stream)
461         throws java.io.InvalidObjectException {
462         throw new java.io.InvalidObjectException("Proxy required");
463     }
464 }
465