001 /*
002 * Copyright 2003-2006 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.util;
027
028 import sun.misc.SharedSecrets;
029
030 /**
031 * A specialized {@link Set} implementation for use with enum types. All of
032 * the elements in an enum set must come from a single enum type that is
033 * specified, explicitly or implicitly, when the set is created. Enum sets
034 * are represented internally as bit vectors. This representation is
035 * extremely compact and efficient. The space and time performance of this
036 * class should be good enough to allow its use as a high-quality, typesafe
037 * alternative to traditional <tt>int</tt>-based "bit flags." Even bulk
038 * operations (such as <tt>containsAll</tt> and <tt>retainAll</tt>) should
039 * run very quickly if their argument is also an enum set.
040 *
041 * <p>The iterator returned by the <tt>iterator</tt> method traverses the
042 * elements in their <i>natural order</i> (the order in which the enum
043 * constants are declared). The returned iterator is <i>weakly
044 * consistent</i>: it will never throw {@link ConcurrentModificationException}
045 * and it may or may not show the effects of any modifications to the set that
046 * occur while the iteration is in progress.
047 *
048 * <p>Null elements are not permitted. Attempts to insert a null element
049 * will throw {@link NullPointerException}. Attempts to test for the
050 * presence of a null element or to remove one will, however, function
051 * properly.
052 *
053 * <P>Like most collection implementations, <tt>EnumSet</tt> is not
054 * synchronized. If multiple threads access an enum set concurrently, and at
055 * least one of the threads modifies the set, it should be synchronized
056 * externally. This is typically accomplished by synchronizing on some
057 * object that naturally encapsulates the enum set. If no such object exists,
058 * the set should be "wrapped" using the {@link Collections#synchronizedSet}
059 * method. This is best done at creation time, to prevent accidental
060 * unsynchronized access:
061 *
062 * <pre>
063 * Set<MyEnum> s = Collections.synchronizedSet(EnumSet.noneOf(MyEnum.class));
064 * </pre>
065 *
066 * <p>Implementation note: All basic operations execute in constant time.
067 * They are likely (though not guaranteed) to be much faster than their
068 * {@link HashSet} counterparts. Even bulk operations execute in
069 * constant time if their argument is also an enum set.
070 *
071 * <p>This class is a member of the
072 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
073 * Java Collections Framework</a>.
074 *
075 * @author Josh Bloch
076 * @version 1.21, 05/05/07
077 * @since 1.5
078 * @see EnumMap
079 * @serial exclude
080 */
081 public abstract class EnumSet<E extends Enum<E>> extends AbstractSet<E>
082 implements Cloneable, java.io.Serializable {
083 /**
084 * The class of all the elements of this set.
085 */
086 final Class<E> elementType;
087
088 /**
089 * All of the values comprising T. (Cached for performance.)
090 */
091 final Enum[] universe;
092
093 private static Enum[] ZERO_LENGTH_ENUM_ARRAY = new Enum[0];
094
095 EnumSet(Class<E> elementType, Enum[] universe) {
096 this .elementType = elementType;
097 this .universe = universe;
098 }
099
100 /**
101 * Creates an empty enum set with the specified element type.
102 *
103 * @param elementType the class object of the element type for this enum
104 * set
105 * @throws NullPointerException if <tt>elementType</tt> is null
106 */
107 public static <E extends Enum<E>> EnumSet<E> noneOf(
108 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<E>(elementType, universe);
115 else
116 return new JumboEnumSet<E>(elementType, universe);
117 }
118
119 /**
120 * Creates an enum set containing all of the elements in the specified
121 * element type.
122 *
123 * @param elementType the class object of the element type for this enum
124 * set
125 * @throws NullPointerException if <tt>elementType</tt> is null
126 */
127 public static <E extends Enum<E>> EnumSet<E> allOf(
128 Class<E> elementType) {
129 EnumSet<E> result = noneOf(elementType);
130 result.addAll();
131 return result;
132 }
133
134 /**
135 * Adds all of the elements from the appropriate enum type to this enum
136 * set, which is empty prior to the call.
137 */
138 abstract void addAll();
139
140 /**
141 * Creates an enum set with the same element type as the specified enum
142 * set, initially containing the same elements (if any).
143 *
144 * @param s the enum set from which to initialize this enum set
145 * @throws NullPointerException if <tt>s</tt> is null
146 */
147 public static <E extends Enum<E>> EnumSet<E> copyOf(EnumSet<E> s) {
148 return s.clone();
149 }
150
151 /**
152 * Creates an enum set initialized from the specified collection. If
153 * the specified collection is an <tt>EnumSet</tt> instance, this static
154 * factory method behaves identically to {@link #copyOf(EnumSet)}.
155 * Otherwise, the specified collection must contain at least one element
156 * (in order to determine the new enum set's element type).
157 *
158 * @param c the collection from which to initialize this enum set
159 * @throws IllegalArgumentException if <tt>c</tt> is not an
160 * <tt>EnumSet</tt> instance and contains no elements
161 * @throws NullPointerException if <tt>c</tt> is null
162 */
163 public static <E extends Enum<E>> EnumSet<E> copyOf(Collection<E> c) {
164 if (c instanceof EnumSet) {
165 return ((EnumSet<E>) c).clone();
166 } else {
167 if (c.isEmpty())
168 throw new IllegalArgumentException(
169 "Collection is empty");
170 Iterator<E> i = c.iterator();
171 E first = i.next();
172 EnumSet<E> result = EnumSet.of(first);
173 while (i.hasNext())
174 result.add(i.next());
175 return result;
176 }
177 }
178
179 /**
180 * Creates an enum set with the same element type as the specified enum
181 * set, initially containing all the elements of this type that are
182 * <i>not</i> contained in the specified set.
183 *
184 * @param s the enum set from whose complement to initialize this enum set
185 * @throws NullPointerException if <tt>s</tt> is null
186 */
187 public static <E extends Enum<E>> EnumSet<E> complementOf(
188 EnumSet<E> s) {
189 EnumSet<E> result = copyOf(s);
190 result.complement();
191 return result;
192 }
193
194 /**
195 * Creates an enum set initially containing the specified element.
196 *
197 * Overloadings of this method exist to initialize an enum set with
198 * one through five elements. A sixth overloading is provided that
199 * uses the varargs feature. This overloading may be used to create
200 * an enum set initially containing an arbitrary number of elements, but
201 * is likely to run slower than the overloadings that do not use varargs.
202 *
203 * @param e the element that this set is to contain initially
204 * @throws NullPointerException if <tt>e</tt> is null
205 * @return an enum set initially containing the specified element
206 */
207 public static <E extends Enum<E>> EnumSet<E> of(E e) {
208 EnumSet<E> result = noneOf(e.getDeclaringClass());
209 result.add(e);
210 return result;
211 }
212
213 /**
214 * Creates an enum set initially containing the specified elements.
215 *
216 * Overloadings of this method exist to initialize an enum set with
217 * one through five elements. A sixth overloading is provided that
218 * uses the varargs feature. This overloading may be used to create
219 * an enum set initially containing an arbitrary number of elements, but
220 * is likely to run slower than the overloadings that do not use varargs.
221 *
222 * @param e1 an element that this set is to contain initially
223 * @param e2 another element that this set is to contain initially
224 * @throws NullPointerException if any parameters are null
225 * @return an enum set initially containing the specified elements
226 */
227 public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2) {
228 EnumSet<E> result = noneOf(e1.getDeclaringClass());
229 result.add(e1);
230 result.add(e2);
231 return result;
232 }
233
234 /**
235 * Creates an enum set initially containing the specified elements.
236 *
237 * Overloadings of this method exist to initialize an enum set with
238 * one through five elements. A sixth overloading is provided that
239 * uses the varargs feature. This overloading may be used to create
240 * an enum set initially containing an arbitrary number of elements, but
241 * is likely to run slower than the overloadings that do not use varargs.
242 *
243 * @param e1 an element that this set is to contain initially
244 * @param e2 another element that this set is to contain initially
245 * @param e3 another element that this set is to contain initially
246 * @throws NullPointerException if any parameters are null
247 * @return an enum set initially containing the specified elements
248 */
249 public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3) {
250 EnumSet<E> result = noneOf(e1.getDeclaringClass());
251 result.add(e1);
252 result.add(e2);
253 result.add(e3);
254 return result;
255 }
256
257 /**
258 * Creates an enum set initially containing the specified elements.
259 *
260 * Overloadings of this method exist to initialize an enum set with
261 * one through five elements. A sixth overloading is provided that
262 * uses the varargs feature. This overloading may be used to create
263 * an enum set initially containing an arbitrary number of elements, but
264 * is likely to run slower than the overloadings that do not use varargs.
265 *
266 * @param e1 an element that this set is to contain initially
267 * @param e2 another element that this set is to contain initially
268 * @param e3 another element that this set is to contain initially
269 * @param e4 another element that this set is to contain initially
270 * @throws NullPointerException if any parameters are null
271 * @return an enum set initially containing the specified elements
272 */
273 public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3,
274 E e4) {
275 EnumSet<E> result = noneOf(e1.getDeclaringClass());
276 result.add(e1);
277 result.add(e2);
278 result.add(e3);
279 result.add(e4);
280 return result;
281 }
282
283 /**
284 * Creates an enum set initially containing the specified elements.
285 *
286 * Overloadings of this method exist to initialize an enum set with
287 * one through five elements. A sixth overloading is provided that
288 * uses the varargs feature. This overloading may be used to create
289 * an enum set initially containing an arbitrary number of elements, but
290 * is likely to run slower than the overloadings that do not use varargs.
291 *
292 * @param e1 an element that this set is to contain initially
293 * @param e2 another element that this set is to contain initially
294 * @param e3 another element that this set is to contain initially
295 * @param e4 another element that this set is to contain initially
296 * @param e5 another element that this set is to contain initially
297 * @throws NullPointerException if any parameters are null
298 * @return an enum set initially containing the specified elements
299 */
300 public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3,
301 E e4, E e5) {
302 EnumSet<E> result = noneOf(e1.getDeclaringClass());
303 result.add(e1);
304 result.add(e2);
305 result.add(e3);
306 result.add(e4);
307 result.add(e5);
308 return result;
309 }
310
311 /**
312 * Creates an enum set initially containing the specified elements.
313 * This factory, whose parameter list uses the varargs feature, may
314 * be used to create an enum set initially containing an arbitrary
315 * number of elements, but it is likely to run slower than the overloadings
316 * that do not use varargs.
317 *
318 * @param first an element that the set is to contain initially
319 * @param rest the remaining elements the set is to contain initially
320 * @throws NullPointerException if any of the specified elements are null,
321 * or if <tt>rest</tt> is null
322 * @return an enum set initially containing the specified elements
323 */
324 public static <E extends Enum<E>> EnumSet<E> of(E first, E... rest) {
325 EnumSet<E> result = noneOf(first.getDeclaringClass());
326 result.add(first);
327 for (E e : rest)
328 result.add(e);
329 return result;
330 }
331
332 /**
333 * Creates an enum set initially containing all of the elements in the
334 * range defined by the two specified endpoints. The returned set will
335 * contain the endpoints themselves, which may be identical but must not
336 * be out of order.
337 *
338 * @param from the first element in the range
339 * @param to the last element in the range
340 * @throws NullPointerException if <tt>first</tt> or <tt>last</tt> are
341 * null
342 * @throws IllegalArgumentException if <tt>first.compareTo(last) > 0</tt>
343 * @return an enum set initially containing all of the elements in the
344 * range defined by the two specified endpoints
345 */
346 public static <E extends Enum<E>> EnumSet<E> range(E from, E to) {
347 if (from.compareTo(to) > 0)
348 throw new IllegalArgumentException(from + " > " + to);
349 EnumSet<E> result = noneOf(from.getDeclaringClass());
350 result.addRange(from, to);
351 return result;
352 }
353
354 /**
355 * Adds the specified range to this enum set, which is empty prior
356 * to the call.
357 */
358 abstract void addRange(E from, E to);
359
360 /**
361 * Returns a copy of this set.
362 *
363 * @return a copy of this set
364 */
365 public EnumSet<E> clone() {
366 try {
367 return (EnumSet<E>) super .clone();
368 } catch (CloneNotSupportedException e) {
369 throw new AssertionError(e);
370 }
371 }
372
373 /**
374 * Complements the contents of this enum set.
375 */
376 abstract void complement();
377
378 /**
379 * Throws an exception if e is not of the correct type for this enum set.
380 */
381 final void typeCheck(E e) {
382 Class eClass = e.getClass();
383 if (eClass != elementType
384 && eClass.getSuperclass() != elementType)
385 throw new ClassCastException(eClass + " != " + elementType);
386 }
387
388 /**
389 * Returns all of the values comprising E.
390 * The result is uncloned, cached, and shared by all callers.
391 */
392 private static <E extends Enum<E>> E[] getUniverse(
393 Class<E> elementType) {
394 return SharedSecrets.getJavaLangAccess()
395 .getEnumConstantsShared(elementType);
396 }
397
398 /**
399 * This class is used to serialize all EnumSet instances, regardless of
400 * implementation type. It captures their "logical contents" and they
401 * are reconstructed using public static factories. This is necessary
402 * to ensure that the existence of a particular implementation type is
403 * an implementation detail.
404 *
405 * @serial include
406 */
407 private static class SerializationProxy<E extends Enum<E>>
408 implements java.io.Serializable {
409 /**
410 * The element type of this enum set.
411 *
412 * @serial
413 */
414 private final Class<E> elementType;
415
416 /**
417 * The elements contained in this enum set.
418 *
419 * @serial
420 */
421 private final Enum[] elements;
422
423 SerializationProxy(EnumSet<E> set) {
424 elementType = set.elementType;
425 elements = (Enum[]) set.toArray(ZERO_LENGTH_ENUM_ARRAY);
426 }
427
428 private Object readResolve() {
429 EnumSet<E> result = EnumSet.noneOf(elementType);
430 for (Enum e : elements)
431 result.add((E) e);
432 return result;
433 }
434
435 private static final long serialVersionUID = 362491234563181265L;
436 }
437
438 Object writeReplace() {
439 return new SerializationProxy<E>(this);
440 }
441 }
|