ACollection
represents a group of objects known as its elements. TheCollection
interface is used to pass around collections of objects where maximum generality is desired. For example, by convention all general-purpose collection implementations have a constructor that takes aCollection
argument. This constructor, known as a conversion constructor, initializes the new collection to contain all the elements in the specified collection, whatever the given collection's subinterface or implementation type. In other words, it allows you to convert the collection's type.Suppose, for example, that you have a
Collection<String> c
, which may be aList
, aSet
, or another kind ofCollection
. This idiom creates a newArrayList
(an implementation of theList
interface), initially containing all the elements inc
.The following shows theList<String> list = new ArrayList<String>(c);Collection
interface.The interface does about what you'd expect, given that apublic interface Collection<E> extends Iterable<E> { // Basic operations int size(); boolean isEmpty(); boolean contains(Object element); boolean add(E element); //optional boolean remove(Object element); //optional Iterator<E> iterator(); // Bulk operations boolean containsAll(Collection<?> c); boolean addAll(Collection<? extends E> c); //optional boolean removeAll(Collection<?> c); //optional boolean retainAll(Collection<?> c); //optional void clear(); //optional // Array operations Object[] toArray(); <T> T[] toArray(T[] a); }Collection
represents a group of objects. The interface has methods to tell you how many elements are in the collection (size
,isEmpty
), to check whether a given object is in the collection (contains
), to add and remove an element from the collection (add
,remove
), and to provide an iterator over the collection (iterator
).The
add
method is defined generally enough so that it makes sense for collections that allow duplicates as well as those that don't. It guarantees that theCollection
will contain the specified element after the call completes, and returnstrue
if theCollection
changes as a result of the call. Similarly, theremove
method is designed to remove a single instance of the specified element from theCollection
, assuming that it contains the element to start with, and to returntrue
if theCollection
was modified as a result.
There are two ways to traverse collections: (1) with thefor-each
construct and (2) by usingIterator
s.for-each Construct
Thefor-each
construct allows you to concisely traverse a collection or array using afor
loop see The for Statement. The following code uses thefor-each
construct to print out each element of a collection on a separate line.for (Object o : collection) System.out.println(o);Iterators
AnIterator
is an object that enables you to traverse through a collection and to remove elements from the collection selectively, if desired. You get anIterator
for a collection by calling itsiterator
method. The following is theIterator
interface.Thepublic interface Iterator<E> { boolean hasNext(); E next(); void remove(); //optional }hasNext
method returnstrue
if the iteration has more elements, and thenext
method returns the next element in the iteration. Theremove
method removes the last element that was returned bynext
from the underlyingCollection
. Theremove
method may be called only once per call tonext
and throws an exception if this rule is violated.Note that
Iterator.remove
is the only safe way to modify a collection during iteration; the behavior is unspecified if the underlying collection is modified in any other way while the iteration is in progress.Use
Iterator
instead of thefor-each
construct when you need to:The following method shows you how to use an
- Remove the current element. The
for-each
construct hides the iterator, so you cannot callremove
. Therefore, thefor-each
construct is not usable for filtering.- Iterate over multiple collections in parallel.
Iterator
to filter an arbitraryCollection
that is, traverse the collection removing specific elements.This simple piece of code is polymorphic, which means that it works for anystatic void filter(Collection<?> c) { for (Iterator<?> it = c.iterator(); it.hasNext(); ) if (!cond(it.next())) it.remove(); }Collection
regardless of implementation. This example demonstrates how easy it is to write a polymorphic algorithm using the Java Collections Framework.
Bulk operations perform an operation on an entireCollection
. You could implement these shorthand operations using the basic operations, though in most cases such implementations would be less efficient. The following are the bulk operations:The
containsAll
returnstrue
if the targetCollection
contains all the elements in the specifiedCollection
.addAll
adds all the elements in the specifiedCollection
to the targetCollection
.removeAll
removes from the targetCollection
all its elements that are also contained in the specifiedCollection
.retainAll
removes from the targetCollection
all its elements that are not also contained in the specifiedCollection
. That is, it retains only those elements in the targetCollection
that are also contained in the specifiedCollection
.clear
removes all elements from theCollection
.addAll
,removeAll
, andretainAll
methods all returntrue
if the targetCollection
was modified in the process of executing the operation.As a simple example of the power of bulk operations, consider the following idiom to remove all instances of a specified element,
e
, from aCollection
,c
.More specifically, suppose you want to remove all thec.removeAll(Collections.singleton(e));null
elements from aCollection
.This idiom usesc.removeAll(Collections.singleton(null));Collections.singleton
, which is a static factory method that returns an immutableSet
containing only the specified element.
ThetoArray
methods are provided as a bridge between collections and older APIs that expect arrays on input. The array operations allow the contents of aCollection
to be translated into an array. The simple form with no arguments creates a new array ofObject
. The more complex form allows the caller to provide an array or to choose the runtime type of the output array.For example, suppose that
c
is aCollection
. The following snippet dumps the contents ofc
into a newly allocated array ofObject
whose length is identical to the number of elements inc
.Suppose thatObject[] a = c.toArray();c
is known to contain only strings (perhaps becausec
is of typeCollection<String>
). The following snippet dumps the contents ofc
into a newly allocated array ofString
whose length is identical to the number of elements inc
.String[] a = c.toArray(new String[0]);