001/* 002 * Copyright (C) 2008 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.collect; 018 019import static com.google.common.base.Preconditions.checkNotNull; 020 021import com.google.common.annotations.GwtCompatible; 022import com.google.errorprone.annotations.CanIgnoreReturnValue; 023import java.io.Serializable; 024import java.util.AbstractCollection; 025import java.util.Collection; 026import java.util.Collections; 027import java.util.Iterator; 028import java.util.List; 029import java.util.Spliterator; 030import java.util.Spliterators; 031import java.util.function.Predicate; 032import org.checkerframework.checker.nullness.qual.Nullable; 033 034/** 035 * A {@link Collection} whose contents will never change, and which offers a few additional 036 * guarantees detailed below. 037 * 038 * <p><b>Warning:</b> avoid <i>direct</i> usage of {@link ImmutableCollection} as a type (just as 039 * with {@link Collection} itself). Prefer subtypes such as {@link ImmutableSet} or {@link 040 * ImmutableList}, which have well-defined {@link #equals} semantics, thus avoiding a common source 041 * of bugs and confusion. 042 * 043 * <h3>About <i>all</i> {@code Immutable-} collections</h3> 044 * 045 * <p>The remainder of this documentation applies to every public {@code Immutable-} type in this 046 * package, whether it is a subtype of {@code ImmutableCollection} or not. 047 * 048 * <h4>Guarantees</h4> 049 * 050 * <p>Each makes the following guarantees: 051 * 052 * <ul> 053 * <li><b>Shallow immutability.</b> Elements can never be added, removed or replaced in this 054 * collection. This is a stronger guarantee than that of {@link 055 * Collections#unmodifiableCollection}, whose contents change whenever the wrapped collection 056 * is modified. 057 * <li><b>Null-hostility.</b> This collection will never contain a null element. 058 * <li><b>Deterministic iteration.</b> The iteration order is always well-defined, depending on 059 * how the collection was created. Typically this is insertion order unless an explicit 060 * ordering is otherwise specified (e.g. {@link ImmutableSortedSet#naturalOrder}). See the 061 * appropriate factory method for details. View collections such as {@link 062 * ImmutableMultiset#elementSet} iterate in the same order as the parent, except as noted. 063 * <li><b>Thread safety.</b> It is safe to access this collection concurrently from multiple 064 * threads. 065 * <li><b>Integrity.</b> This type cannot be subclassed outside this package (which would allow 066 * these guarantees to be violated). 067 * </ul> 068 * 069 * <h4>"Interfaces", not implementations</h4> 070 * 071 * <p>These are classes instead of interfaces to prevent external subtyping, but should be thought 072 * of as interfaces in every important sense. Each public class such as {@link ImmutableSet} is a 073 * <i>type</i> offering meaningful behavioral guarantees. This is substantially different from the 074 * case of (say) {@link HashSet}, which is an <i>implementation</i>, with semantics that were 075 * largely defined by its supertype. 076 * 077 * <p>For field types and method return types, you should generally use the immutable type (such as 078 * {@link ImmutableList}) instead of the general collection interface type (such as {@link List}). 079 * This communicates to your callers all of the semantic guarantees listed above, which is almost 080 * always very useful information. 081 * 082 * <p>On the other hand, a <i>parameter</i> type of {@link ImmutableList} is generally a nuisance to 083 * callers. Instead, accept {@link Iterable} and have your method or constructor body pass it to the 084 * appropriate {@code copyOf} method itself. 085 * 086 * <p>Expressing the immutability guarantee directly in the type that user code references is a 087 * powerful advantage. Although Java offers certain immutable collection factory methods, such as 088 * {@link Collections#singleton(Object)} and <a 089 * href="https://docs.oracle.com/javase/9/docs/api/java/util/Set.html#immutable">{@code Set.of}</a>, 090 * we recommend using <i>these</i> classes instead for this reason (as well as for consistency). 091 * 092 * <h4>Creation</h4> 093 * 094 * <p>Except for logically "abstract" types like {@code ImmutableCollection} itself, each {@code 095 * Immutable} type provides the static operations you need to obtain instances of that type. These 096 * usually include: 097 * 098 * <ul> 099 * <li>Static methods named {@code of}, accepting an explicit list of elements or entries. 100 * <li>Static methods named {@code copyOf} (or {@code copyOfSorted}), accepting an existing 101 * collection whose contents should be copied. 102 * <li>A static nested {@code Builder} class which can be used to populate a new immutable 103 * instance. 104 * </ul> 105 * 106 * <h4>Warnings</h4> 107 * 108 * <ul> 109 * <li><b>Warning:</b> as with any collection, it is almost always a bad idea to modify an element 110 * (in a way that affects its {@link Object#equals} behavior) while it is contained in a 111 * collection. Undefined behavior and bugs will result. It's generally best to avoid using 112 * mutable objects as elements at all, as many users may expect your "immutable" object to be 113 * <i>deeply</i> immutable. 114 * </ul> 115 * 116 * <h4>Performance notes</h4> 117 * 118 * <ul> 119 * <li>Implementations can be generally assumed to prioritize memory efficiency, then speed of 120 * access, and lastly speed of creation. 121 * <li>The {@code copyOf} methods will sometimes recognize that the actual copy operation is 122 * unnecessary; for example, {@code copyOf(copyOf(anArrayList))} should copy the data only 123 * once. This reduces the expense of habitually making defensive copies at API boundaries. 124 * However, the precise conditions for skipping the copy operation are undefined. 125 * <li><b>Warning:</b> a view collection such as {@link ImmutableMap#keySet} or {@link 126 * ImmutableList#subList} may retain a reference to the entire data set, preventing it from 127 * being garbage collected. If some of the data is no longer reachable through other means, 128 * this constitutes a memory leak. Pass the view collection to the appropriate {@code copyOf} 129 * method to obtain a correctly-sized copy. 130 * <li>The performance of using the associated {@code Builder} class can be assumed to be no 131 * worse, and possibly better, than creating a mutable collection and copying it. 132 * <li>Implementations generally do not cache hash codes. If your element or key type has a slow 133 * {@code hashCode} implementation, it should cache it itself. 134 * </ul> 135 * 136 * <h4>Example usage</h4> 137 * 138 * <pre>{@code 139 * class Foo { 140 * private static final ImmutableSet<String> RESERVED_CODES = 141 * ImmutableSet.of("AZ", "CQ", "ZX"); 142 * 143 * private final ImmutableSet<String> codes; 144 * 145 * public Foo(Iterable<String> codes) { 146 * this.codes = ImmutableSet.copyOf(codes); 147 * checkArgument(Collections.disjoint(this.codes, RESERVED_CODES)); 148 * } 149 * } 150 * }</pre> 151 * 152 * <h3>See also</h3> 153 * 154 * <p>See the Guava User Guide article on <a href= 155 * "https://github.com/google/guava/wiki/ImmutableCollectionsExplained"> immutable collections</a>. 156 * 157 * @since 2.0 158 */ 159@GwtCompatible(emulated = true) 160@SuppressWarnings("serial") // we're overriding default serialization 161// TODO(kevinb): I think we should push everything down to "BaseImmutableCollection" or something, 162// just to do everything we can to emphasize the "practically an interface" nature of this class. 163public abstract class ImmutableCollection<E> extends AbstractCollection<E> implements Serializable { 164 /* 165 * We expect SIZED (and SUBSIZED, if applicable) to be added by the spliterator factory methods. 166 * These are properties of the collection as a whole; SIZED and SUBSIZED are more properties of 167 * the spliterator implementation. 168 */ 169 static final int SPLITERATOR_CHARACTERISTICS = 170 Spliterator.IMMUTABLE | Spliterator.NONNULL | Spliterator.ORDERED; 171 172 ImmutableCollection() {} 173 174 /** Returns an unmodifiable iterator across the elements in this collection. */ 175 @Override 176 public abstract UnmodifiableIterator<E> iterator(); 177 178 @Override 179 public Spliterator<E> spliterator() { 180 return Spliterators.spliterator(this, SPLITERATOR_CHARACTERISTICS); 181 } 182 183 private static final Object[] EMPTY_ARRAY = {}; 184 185 @Override 186 public final Object[] toArray() { 187 return toArray(EMPTY_ARRAY); 188 } 189 190 @CanIgnoreReturnValue 191 @Override 192 public final <T> T[] toArray(T[] other) { 193 checkNotNull(other); 194 int size = size(); 195 196 if (other.length < size) { 197 Object[] internal = internalArray(); 198 if (internal != null) { 199 return Platform.copy(internal, internalArrayStart(), internalArrayEnd(), other); 200 } 201 other = ObjectArrays.newArray(other, size); 202 } else if (other.length > size) { 203 other[size] = null; 204 } 205 copyIntoArray(other, 0); 206 return other; 207 } 208 209 /** If this collection is backed by an array of its elements in insertion order, returns it. */ 210 @Nullable 211 Object[] internalArray() { 212 return null; 213 } 214 215 /** 216 * If this collection is backed by an array of its elements in insertion order, returns the offset 217 * where this collection's elements start. 218 */ 219 int internalArrayStart() { 220 throw new UnsupportedOperationException(); 221 } 222 223 /** 224 * If this collection is backed by an array of its elements in insertion order, returns the offset 225 * where this collection's elements end. 226 */ 227 int internalArrayEnd() { 228 throw new UnsupportedOperationException(); 229 } 230 231 @Override 232 public abstract boolean contains(@Nullable Object object); 233 234 /** 235 * Guaranteed to throw an exception and leave the collection unmodified. 236 * 237 * @throws UnsupportedOperationException always 238 * @deprecated Unsupported operation. 239 */ 240 @CanIgnoreReturnValue 241 @Deprecated 242 @Override 243 public final boolean add(E e) { 244 throw new UnsupportedOperationException(); 245 } 246 247 /** 248 * Guaranteed to throw an exception and leave the collection unmodified. 249 * 250 * @throws UnsupportedOperationException always 251 * @deprecated Unsupported operation. 252 */ 253 @CanIgnoreReturnValue 254 @Deprecated 255 @Override 256 public final boolean remove(Object object) { 257 throw new UnsupportedOperationException(); 258 } 259 260 /** 261 * Guaranteed to throw an exception and leave the collection unmodified. 262 * 263 * @throws UnsupportedOperationException always 264 * @deprecated Unsupported operation. 265 */ 266 @CanIgnoreReturnValue 267 @Deprecated 268 @Override 269 public final boolean addAll(Collection<? extends E> newElements) { 270 throw new UnsupportedOperationException(); 271 } 272 273 /** 274 * Guaranteed to throw an exception and leave the collection unmodified. 275 * 276 * @throws UnsupportedOperationException always 277 * @deprecated Unsupported operation. 278 */ 279 @CanIgnoreReturnValue 280 @Deprecated 281 @Override 282 public final boolean removeAll(Collection<?> oldElements) { 283 throw new UnsupportedOperationException(); 284 } 285 286 /** 287 * Guaranteed to throw an exception and leave the collection unmodified. 288 * 289 * @throws UnsupportedOperationException always 290 * @deprecated Unsupported operation. 291 */ 292 @CanIgnoreReturnValue 293 @Deprecated 294 @Override 295 public final boolean removeIf(Predicate<? super E> filter) { 296 throw new UnsupportedOperationException(); 297 } 298 299 /** 300 * Guaranteed to throw an exception and leave the collection unmodified. 301 * 302 * @throws UnsupportedOperationException always 303 * @deprecated Unsupported operation. 304 */ 305 @Deprecated 306 @Override 307 public final boolean retainAll(Collection<?> elementsToKeep) { 308 throw new UnsupportedOperationException(); 309 } 310 311 /** 312 * Guaranteed to throw an exception and leave the collection unmodified. 313 * 314 * @throws UnsupportedOperationException always 315 * @deprecated Unsupported operation. 316 */ 317 @Deprecated 318 @Override 319 public final void clear() { 320 throw new UnsupportedOperationException(); 321 } 322 323 /** 324 * Returns an {@code ImmutableList} containing the same elements, in the same order, as this 325 * collection. 326 * 327 * <p><b>Performance note:</b> in most cases this method can return quickly without actually 328 * copying anything. The exact circumstances under which the copy is performed are undefined and 329 * subject to change. 330 * 331 * @since 2.0 332 */ 333 public ImmutableList<E> asList() { 334 switch (size()) { 335 case 0: 336 return ImmutableList.of(); 337 case 1: 338 return ImmutableList.of(iterator().next()); 339 default: 340 return new RegularImmutableAsList<E>(this, toArray()); 341 } 342 } 343 344 /** 345 * Returns {@code true} if this immutable collection's implementation contains references to 346 * user-created objects that aren't accessible via this collection's methods. This is generally 347 * used to determine whether {@code copyOf} implementations should make an explicit copy to avoid 348 * memory leaks. 349 */ 350 abstract boolean isPartialView(); 351 352 /** 353 * Copies the contents of this immutable collection into the specified array at the specified 354 * offset. Returns {@code offset + size()}. 355 */ 356 @CanIgnoreReturnValue 357 int copyIntoArray(Object[] dst, int offset) { 358 for (E e : this) { 359 dst[offset++] = e; 360 } 361 return offset; 362 } 363 364 Object writeReplace() { 365 // We serialize by default to ImmutableList, the simplest thing that works. 366 return new ImmutableList.SerializedForm(toArray()); 367 } 368 369 /** 370 * Abstract base class for builders of {@link ImmutableCollection} types. 371 * 372 * @since 10.0 373 */ 374 public abstract static class Builder<E> { 375 static final int DEFAULT_INITIAL_CAPACITY = 4; 376 377 static int expandedCapacity(int oldCapacity, int minCapacity) { 378 if (minCapacity < 0) { 379 throw new AssertionError("cannot store more than MAX_VALUE elements"); 380 } 381 // careful of overflow! 382 int newCapacity = oldCapacity + (oldCapacity >> 1) + 1; 383 if (newCapacity < minCapacity) { 384 newCapacity = Integer.highestOneBit(minCapacity - 1) << 1; 385 } 386 if (newCapacity < 0) { 387 newCapacity = Integer.MAX_VALUE; 388 // guaranteed to be >= newCapacity 389 } 390 return newCapacity; 391 } 392 393 Builder() {} 394 395 /** 396 * Adds {@code element} to the {@code ImmutableCollection} being built. 397 * 398 * <p>Note that each builder class covariantly returns its own type from this method. 399 * 400 * @param element the element to add 401 * @return this {@code Builder} instance 402 * @throws NullPointerException if {@code element} is null 403 */ 404 @CanIgnoreReturnValue 405 public abstract Builder<E> add(E element); 406 407 /** 408 * Adds each element of {@code elements} to the {@code ImmutableCollection} being built. 409 * 410 * <p>Note that each builder class overrides this method in order to covariantly return its own 411 * type. 412 * 413 * @param elements the elements to add 414 * @return this {@code Builder} instance 415 * @throws NullPointerException if {@code elements} is null or contains a null element 416 */ 417 @CanIgnoreReturnValue 418 public Builder<E> add(E... elements) { 419 for (E element : elements) { 420 add(element); 421 } 422 return this; 423 } 424 425 /** 426 * Adds each element of {@code elements} to the {@code ImmutableCollection} being built. 427 * 428 * <p>Note that each builder class overrides this method in order to covariantly return its own 429 * type. 430 * 431 * @param elements the elements to add 432 * @return this {@code Builder} instance 433 * @throws NullPointerException if {@code elements} is null or contains a null element 434 */ 435 @CanIgnoreReturnValue 436 public Builder<E> addAll(Iterable<? extends E> elements) { 437 for (E element : elements) { 438 add(element); 439 } 440 return this; 441 } 442 443 /** 444 * Adds each element of {@code elements} to the {@code ImmutableCollection} being built. 445 * 446 * <p>Note that each builder class overrides this method in order to covariantly return its own 447 * type. 448 * 449 * @param elements the elements to add 450 * @return this {@code Builder} instance 451 * @throws NullPointerException if {@code elements} is null or contains a null element 452 */ 453 @CanIgnoreReturnValue 454 public Builder<E> addAll(Iterator<? extends E> elements) { 455 while (elements.hasNext()) { 456 add(elements.next()); 457 } 458 return this; 459 } 460 461 /** 462 * Returns a newly-created {@code ImmutableCollection} of the appropriate type, containing the 463 * elements provided to this builder. 464 * 465 * <p>Note that each builder class covariantly returns the appropriate type of {@code 466 * ImmutableCollection} from this method. 467 */ 468 public abstract ImmutableCollection<E> build(); 469 } 470}