Iterator

An Iterator is a way to step over each element in a collection without exposing the collection's underlying representation to clients. In JAVA, it is sometimes quicker to use the for-each loop, but Iterators are still needed in some cases. The Iterator design in JAVA is arguably broken, see Command query separation.

Use When

Use the iterator pattern when:

• You want to access the contents of a collection sequentially without exposing the collection's underlying representation to clients.
• You want to support multiple traversals of a collection.
• You want to provide the same interface for traversing different collections.

Structure

Participants

Iterator

Iterator defines the interface for accessing elements and traversing the collection.

ConcreteIterator

ConcreteIterator implements in interface defined by Iterator. It keeps track of the current position of the traversal in the collection.

Aggregate

Aggregate defines an interface for creating an iterator for itself.

ConcreteAggregate

ConcreteAggregate implements the operation to create an iterator by returning an instance of ConcreteIterator.

Examples

A simple use of an Iterator to print out all names in a collection in JAVA:

Collection<String> names = new HashSet<String>();
...
Iterator<String> myIterator = names.iterator();
while(myIterator.hasNext()) {
  String name = myIterator.next();
  System.out.println(name);
}

The for-each loop in JAVA can perform the same task, in a somewhat neater fashion (syntactically):

Collection<String> names = new HashSet<String>();
...
for(String name : names) {
  System.out.println(name);
}

However, consider the following example:

Collection<String> names = new HashSet<String>();
...
public void removeNames(String lastName) {
  for(String name : names) {
    if(name > lastName)
      names.remove(name);
  }
}

This valid looking code will throw a ConcurrentModificationException, as directly removing an element from a collection while stepping through the collection could cause the code to "get lost". In this example, an Iterator should be used:

Collection<String> names = new HashSet<String>();
...
public void removeNames(String lastName) {
  Iterator<String> myIterator = names.iterator();
  while(myIterator.hasNext()) {
    String name = myIterator.next();
    if(name > lastName)
      myIterator.remove();
  }
}

Consequences

• The Iterator pattern makes it easy to define several different ways to traverse a collection by simply adding Iterator subclasses.
• The Iterator pattern simplifies the Aggregate interface because it encapsulates all the traversal behavior.
• The Iterator pattern allows more than one traversal of a single collection at the same time.

Related Patterns

• Composite: Iterator is useful for traversing recursive structures like composites.
• Factory Method: Polymorphic iterators require a factory method to ensure that the correct iterator is created.
• Memento: This pattern is often used by iterators to capture the state of a traversal. The iterator often stores the Memento internally rather than using a separate Caretaker.