Understanding Java Iterator API: Methods, Principles, Usage, and Common Pitfalls

1. Iterator API

Java's Iterator provides three main methods: hasNext(), next(), and remove().

hasNext: checks if there is a next element without moving the cursor.

next: moves the cursor forward and returns the element at the new position.

remove: deletes the element currently pointed to by the cursor, typically used after next().

2. How Iterator Works

When an Iterator is created for a collection, its internal cursor starts before the first element (int cursor = 0).

Calling hasNext() only checks for the presence of a subsequent element; it does not move the cursor.

Calling next() advances the cursor and returns the element; if no element exists, an exception is thrown.

remove() deletes the element that the cursor currently points to; if the cursor is not positioned on an element, an exception is thrown.

3. Typical Uses of Iterator

Iterators are primarily used for traversing collections.

4. Common Pitfalls and Solutions

Java's Iterator follows a fail‑fast design. If a collection is modified by another method while an Iterator is iterating, a ConcurrentModificationException is thrown.

Thus, in the face of concurrent modification, the iterator fails quickly and cleanly, rather than risking arbitrary, non‑deterministic behavior at an undetermined time in the future.

To avoid this exception, you can:

1. In a single‑threaded context, use iterator.remove() after retrieving an element with next() to ensure the cursor remains consistent.

while (iterator.hasNext()) {
    Object item = iterator.next();
    iterator.remove(); // Important! Avoid ConcurrentModificationException
    // ...
}

2. In a multi‑threaded context, use thread‑safe collections from java.util.concurrent to prevent concurrent modifications.

This exception may be thrown by methods that have detected concurrent modification of an object when such modification is not permissible.

Finally, ConcurrentModificationException should be used only to signal a bug, not as a mechanism for normal program flow (e.g., try…catch for control).