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