java.util
Interface Iterator<E>

All Superinterfaces:

java.lang.SimpleIterator

public interface Iterator<E>

extends java.lang.SimpleIterator<E>

An iterator over a collection. Iterator takes the place of Enumeration in the Java collections framework. Iterators differ from enumerations in two ways:

• Iterators allow the caller to remove elements from the underlying collection during the iteration with well-defined semantics.
• Method names have been improved.

Iterator implementations should document their properties when the collections they iterate over are modified in the course of traversal. These properties may differ when modifications occur in the same thread as the iterator versus in other threads. Here is a non-exhaustive list of categories that implementations may conform to:

Synchronizable fail-fast

This policy is the most common choice for collections in package java.util: If the underlying collection is modified (except via Iterator.remove) in the same thread, calls to Iterator.next will throw ConcurrentModificationException. If a traversal is performed within the scope of a specified lock, the implementation guarantees that no modifications will be performed by other threads using this lock during traversal, so these kinds of ConcurrentModificationException will not occur. If traversal is not protected by the specified lock, and/or other threads perform modifications without holding this lock, these modifications may lead to ConcurrentModificationException, internal corruption of the Iterator, or both.

Weakly consistent

This policy is the most common choice for collections in package java.util.concurrent: Iterator.next returns elements reflecting the state of the collection as it existed at or since construction of the Iterator. There is no guarantee whether an element added or removed by any thread subsequent to construction of an Iterator will or will not be returned by some call to its Iterator.next method. The method will never throw ConcurrentModificationException.

Snapshot

Iterator.next returns elements reflecting the state of the collection as it existed upon construction of the Iterator. Subsequent modifications are guaranteed not to be reflected by the Iterator. For example, an element added subsequent to construction of the iterator will not be returned by any call to its Iterator.next method. The method will never throw ConcurrentModificationException.

Synchronous

All modifications of the collection are observed by the iterator. This is in general possible only for collections whose size cannot change during traversal (in which case the Iterator does not support Iterator.remove). The method will never throw ConcurrentModificationException.

Corruptible

If the underlying collection is modified while iterating, the behavior of the Iterator becomes undefined, and almost surely erroneous.

Unless otherwise specified, an Iterator makes no promises about the order in which elements are provided in method Iterator.next.

Unless otherwise specified to allow this, a given Iterator should not be shared across multiple threads. Calls to Iterator.next for the same iterator from multiple threads result in undefined, usually erroneous, behavior.

This interface is a member of the Java Collections Framework.

Since:

1.2

Version:

1.20, 05/20/03

Author:

Josh Bloch

See Also:

Collection, ListIterator, Enumeration

Method Summary

boolean	hasNext() Returns true if the iteration has more elements.
E	next() Returns the next element in the iteration.
void	remove() Removes from the underlying collection the last element returned by the iterator (optional operation).

Method Detail

hasNext

public boolean hasNext()

Returns true if the iteration has more elements. (In other words, returns true if next would return an element rather than throwing an exception.)

Specified by:

hasNext in interface java.lang.SimpleIterator

Returns:

true if the iterator has more elements.

next

public E next()

Returns the next element in the iteration.

Specified by:

next in interface java.lang.SimpleIterator

Returns:

the next element in the iteration.

Throws:

NoSuchElementException - iteration has no more elements.

remove

public void remove()

Removes from the underlying collection the last element returned by the iterator (optional operation). This method can be called only once per call to next.

Throws:

java.lang.UnsupportedOperationException - if the remove operation is not supported by this Iterator.

java.lang.IllegalStateException - if the next method has not yet been called, or the remove method has already been called after the last call to the next method.