@GwtCompatible(emulated=true) public abstract class ImmutableCollection<E> extends AbstractCollection<E> implements Serializable
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
semantics, thus avoiding a common source of bugs and confusion.
Immutable-
collectionsThe remainder of this documentation applies to every public Immutable-
type in this package, whether it is a subtype of ImmutableCollection
or not.
Each makes the following guarantees:
Collections.unmodifiableCollection(java.util.Collection<? extends T>)
, whose contents change whenever the wrapped collection is modified. Multiset.elementSet()
iterate in the same order as the parent, except as noted. 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.
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:
of
, accepting an explicit list of elements or entries. copyOf
(or copyOfSorted
), accepting an existing collection whose contents should be copied. Builder
class which can be used to populate a new immutable instance. 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. 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. 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. Builder
class can be assumed to be no worse, and possibly better, than creating a mutable collection and copying it. hashCode
implementation, it should cache it itself. 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 the Guava User Guide article on immutable collections.
Modifier and Type | Class and Description |
---|---|
static class |
ImmutableCollection
Abstract base class for builders of
ImmutableCollection types.
|
Modifier and Type | Method and Description |
---|---|
boolean |
add(E e)
Deprecated.
Unsupported operation.
|
boolean |
addAll(Collection
Deprecated.
Unsupported operation.
|
ImmutableList |
asList()
Returns an
ImmutableList containing the same elements, in the same order, as this collection.
|
void |
clear()
Deprecated.
Unsupported operation.
|
abstract boolean |
contains(Object
|
abstract UnmodifiableIterator |
iterator()
Returns an unmodifiable iterator across the elements in this collection.
|
boolean |
remove(Object
Deprecated.
Unsupported operation.
|
boolean |
removeAll(Collection
Deprecated.
Unsupported operation.
|
boolean |
retainAll(Collection
Deprecated.
Unsupported operation.
|
Object |
toArray()
|
<T> T[] |
toArray(T[] other)
|
containsAll, isEmpty, size, toString
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
equals, hashCode, parallelStream, removeIf, spliterator, stream
public abstract UnmodifiableIterator<E> iterator()
public final Object[] toArray()
public final <T> T[] toArray(T[] other)
public abstract boolean contains(Objectobject)
@Deprecated public final boolean add(E e)
add
in interface
Collection<E>
add
in class
AbstractCollection<E>
UnsupportedOperationException
- always
@Deprecated public final boolean remove(Objectobject)
remove
in interface
Collection<E>
remove
in class
AbstractCollection<E>
UnsupportedOperationException
- always
@Deprecated public final boolean addAll(Collection<? extends E> newElements)
addAll
in interface
Collection<E>
addAll
in class
AbstractCollection<E>
UnsupportedOperationException
- always
@Deprecated public final boolean removeAll(Collection<?> oldElements)
removeAll
in interface
Collection<E>
removeAll
in class
AbstractCollection<E>
UnsupportedOperationException
- always
@Deprecated public final boolean retainAll(Collection<?> elementsToKeep)
retainAll
in interface
Collection<E>
retainAll
in class
AbstractCollection<E>
UnsupportedOperationException
- always
@Deprecated public final void clear()
clear
in interface
Collection<E>
clear
in class
AbstractCollection<E>
UnsupportedOperationException
- always
public ImmutableList<E> asList()
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.