@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.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.
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.Builder<E>
Abstract base class for builders of
ImmutableCollection types. |
| Modifier and Type | Method and Description |
|---|---|
boolean |
add(E e)
Deprecated.
Unsupported operation.
|
boolean |
addAll(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(Object object) |
abstract UnmodifiableIterator<E> |
iterator()
Returns an unmodifiable iterator across the elements in this collection.
|
boolean |
remove(Object object)
Deprecated.
Unsupported operation.
|
boolean |
removeAll(Collection<?> oldElements)
Deprecated.
Unsupported operation.
|
boolean |
retainAll(Collection<?> elementsToKeep)
Deprecated.
Unsupported operation.
|
Object[] |
toArray() |
<T> T[] |
toArray(T[] other) |
containsAll, isEmpty, size, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitequals, hashCode, parallelStream, removeIf, spliterator, streampublic abstract UnmodifiableIterator<E> iterator()
iterator in interface Iterable<E>iterator in interface Collection<E>iterator in class AbstractCollection<E>public final Object[] toArray()
toArray in interface Collection<E>toArray in class AbstractCollection<E>public final <T> T[] toArray(T[] other)
toArray in interface Collection<E>toArray in class AbstractCollection<E>public abstract boolean contains(@Nullable Object object)
contains in interface Collection<E>contains in class AbstractCollection<E>@Deprecated public final boolean add(E e)
add in interface Collection<E>add in class AbstractCollection<E>UnsupportedOperationException - always@Deprecated public final boolean remove(Object object)
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 - alwayspublic 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.
Copyright © 2010–2017. All rights reserved.