Package com.google.common.collect

Class ImmutableCollection<E>

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<E>, java.util.Collection<E>
    Direct Known Subclasses:
    ImmutableList, ImmutableMultiset, ImmutableSet
    @DoNotMock("Use ImmutableList.of or another implementation")
@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. Typically this is insertion order unless an explicit ordering is otherwise specified (e.g. ImmutableSortedSet.naturalOrder()). See the appropriate factory method for details. View collections such as ImmutableMultiset.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

    These are classes instead of interfaces to prevent external subtyping, but should be thought of as interfaces in every important sense. Each public class such as ImmutableSet is a type offering meaningful behavioral guarantees. This is substantially different from the case of (say) HashSet, which is an implementation, with semantics that were largely defined by its supertype.

    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.

    Expressing the immutability guarantee directly in the type that user code references is a powerful advantage. Although Java offers certain immutable collection factory methods, such as Collections.singleton(Object) and Set.of, we recommend using these classes instead for this reason (as well as for consistency).

    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

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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 extends @Nullable java.lang.Object>
      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, parallelStream, removeIf, spliterator, stream, toArray

      • Methods inherited from interface java.lang.Iterable

        forEach

    • Method Detail

      • iterator

        public abstract UnmodifiableIterator<E> iterator()
        Returns an unmodifiable iterator across the elements in this collection.
        Specified by:
        iterator in interface java.util.Collection<E>
        Specified by:
        iterator in interface java.lang.Iterable<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

        @CanIgnoreReturnValue
public final <T extends @Nullable java.lang.Object> 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​(@CheckForNull
                                 java.lang.Object object)
        Specified by:
        contains in interface java.util.Collection<E>
        Overrides:
        contains in class java.util.AbstractCollection<E>

      • add

        @CanIgnoreReturnValue
@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

        @CanIgnoreReturnValue
@Deprecated
public final boolean remove​(@CheckForNull
                            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

        @CanIgnoreReturnValue
@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

        @CanIgnoreReturnValue
@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

        @CanIgnoreReturnValue
@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