ImmutableCollection
Date: 2016-05-24

com.google.common.collect

## Class ImmutableCollection<E>

- java.lang.Object
- - java.util.AbstractCollection<E>
  - - com.google.common.collect.ImmutableCollection<E>

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<E>, java.util.Collection<E>
  Direct Known Subclasses:
    ImmutableList, ImmutableMultiset, ImmutableSet

      @GwtCompatible(emulated=true)
      public abstract class ImmutableCollection<E>
      extends java.util.AbstractCollection<E>
      implements java.io.Serializable

  A `Collection` whose contents will never change, and which offers a few additional guarantees detailed below.

  Warning: avoid direct usage of `ImmutableCollection` as a type (just as with `Collection` itself). Prefer subtypes such as `ImmutableSet` or `ImmutableList`, which have well-defined `Object.equals(java.lang.Object)` semantics, thus avoiding a common source of bugs and confusion.

  ### About all `Immutable-` collections

  The remainder of this documentation applies to every public `Immutable-` type in this package, whether it is a subtype of `ImmutableCollection` or not.

  #### Guarantees

  Each makes the following guarantees:

  - Shallow immutability. Elements can never be added, removed or replaced in this collection. This is a stronger guarantee than that of `Collections.unmodifiableCollection(java.util.Collection<? extends T>)`, whose contents change whenever the wrapped collection is modified.
  - Null-hostility. This collection will never contain a null element.
  - Deterministic iteration. The iteration order is always well-defined, depending on how the collection was created (see the appropriate factory method for details). View collections such as `Multiset.elementSet()` iterate in the same order as the parent, except as noted.
  - Thread safety. It is safe to access this collection concurrently from multiple threads.
  - Integrity. This type cannot be subclassed outside this package (which would allow these guarantees to be violated).

  #### "Interfaces", not implementations

  Each public class, such as `ImmutableSet`, is a type offering meaningful behavioral guarantees -- not merely a specific implementation as in the case of, say, `ArrayList`. You should treat them as interfaces in every important sense of the word.

  For field types and method return types, you should generally use the immutable type (such as `ImmutableList`) instead of the general collection interface type (such as `List`). This communicates to your callers all of the semantic guarantees listed above, which is almost always very useful information.

  On the other hand, a parameter type of `ImmutableList` is generally a nuisance to callers. Instead, accept `Iterable` and have your method or constructor body pass it to the appropriate `copyOf` method itself.

  #### Creation

  Except for logically "abstract" types like `ImmutableCollection` itself, each `Immutable` type provides the static operations you need to obtain instances of that type. These usually include:

  - Static methods named `of`, accepting an explicit list of elements or entries.
  - Static methods named `copyOf` (or `copyOfSorted`), accepting an existing collection whose contents should be copied.
  - A static nested `Builder` class which can be used to populate a new immutable instance.

  #### Warnings

  - Warning: as with any collection, it is almost always a bad idea to modify an element (in a way that affects its `Object.equals(java.lang.Object)` behavior) while it is contained in a collection. Undefined behavior and bugs will result. It's generally best to avoid using mutable objects as elements at all, as many users may expect your "immutable" object to be deeply immutable.

  #### Performance notes

  - Implementations can be generally assumed to prioritize memory efficiency, then speed of access, and lastly speed of creation.
  - The `copyOf` methods will sometimes recognize that the actual copy operation is unnecessary; for example, `copyOf(copyOf(anArrayList))` should copy the data only once. This reduces the expense of habitually making defensive copies at API boundaries. However, the precise conditions for skipping the copy operation are undefined.
  - Warning: a view collection such as `ImmutableMap.keySet` or `ImmutableList.subList(int, int)` may retain a reference to the entire data set, preventing it from being garbage collected. If some of the data is no longer reachable through other means, this constitutes a memory leak. Pass the view collection to the appropriate `copyOf` method to obtain a correctly-sized copy.
  - The performance of using the associated `Builder` class can be assumed to be no worse, and possibly better, than creating a mutable collection and copying it.
  - Implementations generally do not cache hash codes. If your element or key type has a slow `hashCode` implementation, it should cache it itself.

  #### Example usage

         class Foo {
           private static final ImmutableSet<String> RESERVED_CODES =
               ImmutableSet.of("AZ", "CQ", "ZX");

           private final ImmutableSet<String> codes;

           public Foo(Iterable<String> codes) {
             this.codes = ImmutableSet.copyOf(codes);
             checkArgument(Collections.disjoint(this.codes, RESERVED_CODES));
           }
         }

  ### See also

  See the Guava User Guide article on immutable collections.

  Since:
    2.0
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ImmutableCollection.Builder<E>` Abstract base class for builders of `ImmutableCollection` types.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(E e)` Deprecated. Unsupported operation.
    `boolean` | `addAll(java.util.Collection<? extends E> newElements)` Deprecated. Unsupported operation.
    `ImmutableList<E>` | `asList()` Returns an `ImmutableList` containing the same elements, in the same order, as this collection.
    `void` | `clear()` Deprecated. Unsupported operation.
    `abstract boolean` | `contains(java.lang.Object object)`
    `abstract UnmodifiableIterator<E>` | `iterator()` Returns an unmodifiable iterator across the elements in this collection.
    `boolean` | `remove(java.lang.Object object)` Deprecated. Unsupported operation.
    `boolean` | `removeAll(java.util.Collection<?> oldElements)` Deprecated. Unsupported operation.
    `boolean` | `retainAll(java.util.Collection<?> elementsToKeep)` Deprecated. Unsupported operation.
    `java.lang.Object[]` | `toArray()`
    `<T> T[]` | `toArray(T[] other)`

    - ### Methods inherited from class java.util.AbstractCollection

      `containsAll, isEmpty, size, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.Collection

      `equals, hashCode`

- - ### Method Detail

    - #### iterator

          public abstract UnmodifiableIterator<E> iterator()

      Returns an unmodifiable iterator across the elements in this collection.
      Specified by:
        `iterator` in interface `java.lang.Iterable<E>`
      Specified by:
        `iterator` in interface `java.util.Collection<E>`
      Specified by:
        `iterator` in class `java.util.AbstractCollection<E>`

    - #### toArray

          public final java.lang.Object[] toArray()

      Specified by:
        `toArray` in interface `java.util.Collection<E>`
      Overrides:
        `toArray` in class `java.util.AbstractCollection<E>`

    - #### toArray

          public final <T> T[] toArray(T[] other)

      Specified by:
        `toArray` in interface `java.util.Collection<E>`
      Overrides:
        `toArray` in class `java.util.AbstractCollection<E>`

    - #### contains

          public abstract boolean contains(@Nullable
                         java.lang.Object object)

      Specified by:
        `contains` in interface `java.util.Collection<E>`
      Overrides:
        `contains` in class `java.util.AbstractCollection<E>`

    - #### add

          @Deprecated
          public final boolean add(E e)

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the collection unmodified.
      Specified by:
        `add` in interface `java.util.Collection<E>`
      Overrides:
        `add` in class `java.util.AbstractCollection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### remove

          @Deprecated
          public final boolean remove(java.lang.Object object)

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the collection unmodified.
      Specified by:
        `remove` in interface `java.util.Collection<E>`
      Overrides:
        `remove` in class `java.util.AbstractCollection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### addAll

          @Deprecated
          public final boolean addAll(java.util.Collection<? extends E> newElements)

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the collection unmodified.
      Specified by:
        `addAll` in interface `java.util.Collection<E>`
      Overrides:
        `addAll` in class `java.util.AbstractCollection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### removeAll

          @Deprecated
          public final boolean removeAll(java.util.Collection<?> oldElements)

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the collection unmodified.
      Specified by:
        `removeAll` in interface `java.util.Collection<E>`
      Overrides:
        `removeAll` in class `java.util.AbstractCollection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### retainAll

          @Deprecated
          public final boolean retainAll(java.util.Collection<?> elementsToKeep)

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the collection unmodified.
      Specified by:
        `retainAll` in interface `java.util.Collection<E>`
      Overrides:
        `retainAll` in class `java.util.AbstractCollection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### clear

          @Deprecated
          public final void clear()

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the collection unmodified.
      Specified by:
        `clear` in interface `java.util.Collection<E>`
      Overrides:
        `clear` in class `java.util.AbstractCollection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### asList

          public ImmutableList<E> asList()

      Returns an `ImmutableList` containing the same elements, in the same order, as this collection.

      Performance note: in most cases this method can return quickly without actually copying anything. The exact circumstances under which the copy is performed are undefined and subject to change.

      Since:
        2.0