@GwtCompatible(emulated=true) public abstract class ImmutableCollection<E> extends java.util.AbstractCollection<E> implements java.io.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.equals(java.lang.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.
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.
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 9 offers certain immutable collection factory methods, like Set.of
,
we recommend continuing to use these immutable collection classes for this reason.
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.Builder<E>
Abstract base class for builders of
ImmutableCollection types. |
Modifier and Type | Field and Description |
---|---|
private static java.lang.Object[] |
EMPTY_ARRAY |
(package private) static int |
SPLITERATOR_CHARACTERISTICS |
Constructor and Description |
---|
ImmutableCollection() |
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) |
(package private) int |
copyIntoArray(java.lang.Object[] dst,
int offset)
Copies the contents of this immutable collection into the specified array at the specified
offset.
|
(package private) abstract boolean |
isPartialView()
Returns
true if this immutable collection's implementation contains references to
user-created objects that aren't accessible via this collection's methods. |
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 |
removeIf(java.util.function.Predicate<? super E> filter)
Deprecated.
Unsupported operation.
|
boolean |
retainAll(java.util.Collection<?> elementsToKeep)
Deprecated.
Unsupported operation.
|
java.util.Spliterator<E> |
spliterator() |
java.lang.Object[] |
toArray() |
<T> T[] |
toArray(T[] other) |
(package private) java.lang.Object |
writeReplace() |
static final int SPLITERATOR_CHARACTERISTICS
private static final java.lang.Object[] EMPTY_ARRAY
public abstract UnmodifiableIterator<E> iterator()
public java.util.Spliterator<E> spliterator()
public final java.lang.Object[] toArray()
public final <T> T[] toArray(T[] other)
public abstract boolean contains(java.lang.Object object)
@Deprecated public final boolean add(E e)
@Deprecated public final boolean remove(java.lang.Object object)
@Deprecated public final boolean addAll(java.util.Collection<? extends E> newElements)
@Deprecated public final boolean removeAll(java.util.Collection<?> oldElements)
@Deprecated public final boolean removeIf(java.util.function.Predicate<? super E> filter)
removeIf
in interface java.util.Collection<E>
java.lang.UnsupportedOperationException
- always@Deprecated public final boolean retainAll(java.util.Collection<?> elementsToKeep)
@Deprecated public final void clear()
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.
abstract boolean isPartialView()
true
if this immutable collection's implementation contains references to
user-created objects that aren't accessible via this collection's methods. This is generally
used to determine whether copyOf
implementations should make an explicit copy to avoid
memory leaks.int copyIntoArray(java.lang.Object[] dst, int offset)
offset + size()
.java.lang.Object writeReplace()