Iterating Collections in Java

Java provides multiple ways to iterate over collections, each with different performance characteristics and safety guarantees. Understanding the iteration mechanisms — and their failure modes — is essential for writing correct, performant collection code.

Introduction

Every Java collection eventually needs to be traversed — and getting iteration wrong is a source of real production bugs. The ConcurrentModificationException that crashes a server mid-request happens when a collection is structurally modified (add, remove, clear) while being iterated with a standard fail-fast iterator. The fix is always the same pattern: use iterator.remove() instead of collection.remove(). But understanding why requires knowing how the iterator’s internal expectedModCount tracks the collection’s modCount — and where that tracking fails to catch concurrent modifications.

Beyond the concurrent modification problem, iteration performance varies dramatically across collection types. ArrayList iteration is cache-friendly — elements sit in contiguous memory and the CPU prefetches efficiently. LinkedList iteration is pointer-chasing — each node is scattered in memory, and the CPU cannot prefetch what it has not yet reached. The difference shows up as 2-5x slower traversal in practice, often misidentified as a network or computation bottleneck.

This post covers the iteration mechanisms available in Java: Iterator for forward traversal with safe removal, ListIterator for bidirectional traversal and positional modifications, enhanced for-each for clean read-only traversal, and forEach() (Java 8+) for functional-style operations. You will see the fail-fast vs fail-safe distinction, the mechanics of concurrent modification detection, and the performance trade-offs that differentiate array-backed collections from linked ones.

When to Use Each Iteration Style

The Iterator Interface

public interface Iterator<E> {
    boolean hasNext();
    E next();
    void remove();  // Optional, removes last element returned by next()
    default void forEachRemaining(Consumer<? super E> action) { }
}

Fail-Fast vs Fail-Safe

Java’s standard collection iterators (from ArrayList, HashSet, etc.) are fail-fast: they detect concurrent modification and throw ConcurrentModificationException. This is a best-effort detection — not a guarantee — because the modCount check happens only at unsafe points.

Fail-safe iterators (from ConcurrentHashMap, CopyOnWriteArrayList, etc.) work on a copy of the collection and will not throw ConcurrentModificationException.

Mermaid Diagram: Iterator and Collection Relationship

sequenceDiagram
    participant Client
    participant Iterator
    participant Collection
    Client->>Collection: iterator()
    Collection->>Iterator: create Iterator(cursor=0, lastReturned=null)
    Iterator-->>Client: Iterator instance
    loop while it.hasNext()
        Client->>Iterator: next()
        Iterator->>Collection: expectedModCount == modCount?
        Collection-->>Iterator: true
        Iterator->>Iterator: advance cursor, update lastReturned
        Iterator-->>Client: element
    end
    alt concurrent modification detected
        Iterator->>Client: ConcurrentModificationException
    end

Failure Scenarios

Trade-Off Table

Code Snippets

Safe Removal with Iterator

List<String> list = new ArrayList<>(List.of("a", "b", "c", "d"));
Iterator<String> it = list.iterator();
while (it.hasNext()) {
    String s = it.next();
    if (s.equals("b") || s.equals("c")) {
        it.remove();  // Safe — uses iterator's internal state
    }
}
// list = ["a", "d"]

ListIterator for Bidirectional Traversal

List<String> list = new ArrayList<>(List.of("x", "y", "z"));
ListIterator<String> it = list.listIterator();

it.next();          // "x"
it.next();          // "y"
it.previous();      // "y"
it.set("Y");        // Replace "y" with "Y"
it.add("new");      // Insert after "Y"
// list = ["x", "Y", "new", "z"]

forEachRemaining with Lambda

List<Integer> nums = List.of(1, 2, 3, 4, 5);
Iterator<Integer> it = nums.iterator();
it.forEachRemaining(n -> {
    if (n % 2 == 0) System.out.println(n);  // 2, 4
});

Iterating Different Collection Types

// Set — no guaranteed order
Set<String> set = new HashSet<>(List.of("a", "b", "c"));
for (String s : set) { System.out.println(s); }

// Map — iterate entries, keys, or values
Map<String, Integer> map = new HashMap<>();
map.put("key1", 1);
map.put("key2", 2);
for (Map.Entry<String, Integer> e : map.entrySet()) {
    System.out.println(e.getKey() + " = " + e.getValue());
}

Observability Checklist

• Monitor ConcurrentModificationException occurrences — they indicate structural modifications during iteration
• Profile iteration time in hot paths — especially for LinkedList where random access is O(n) per index
• Track forEach() call patterns — functional iteration can allocate lambda objects in hot paths
• Check for repeated .iterator() calls in loops — prefer creating the iterator once and reusing it
• Log iteration patterns over ConcurrentHashMap to detect potential race conditions

Security Notes

• Fail-safe iterators work on copies — be aware that iterating over a snapshot may miss concurrent updates
• When iterating over collections containing sensitive data, ensure the iteration does not leak elements through toString(), logging, or exception messages
• CopyOnWriteArrayList creates a full copy on each mutation — it is safe for read-heavy workloads but expensive for write-heavy ones
• Avoid serializing iterators — they do not carry meaningful state that survives deserialization

Common Pitfalls / Anti-Patterns

1. Calling remove() before next(): Throws IllegalStateException — you must call next() at least once before calling remove()
2. Using for-each for removal: The for-each loop hides the iterator, so you cannot call remove() directly — use an explicit iterator
3. Modifying during forEachRemaining: Can throw ConcurrentModificationException if the collection is structurally modified
4. remove() vs removeAll() during iteration: Calling collection.removeAll(collection) while iterating over the same collection triggers ConcurrentModificationException
5. Assuming order in HashSet iteration: HashSet does not guarantee iteration order; use LinkedHashSet for insertion-order or TreeSet for sorted-order iteration

Quick Recap

• Use Iterator for forward iteration with safe removal
• Use ListIterator for bidirectional traversal and modifications at arbitrary positions
• Use for-each for simple read-only loops
• Use forEach() (Java 8+) for functional-style operations
• Standard iterators are fail-fast — they detect and throw on concurrent modification
• Always prefer iterator.remove() over collection.remove() when iterating

Interview Questions

Iterator<E> it = collection.iterator();\nwhile (it.hasNext()) {\n    if (condition(it.next())) {\n        it.remove();  // Safe — updates internal state\n    }\n}

Further Reading

• Oracle Iterator Documentation — Official Iterator interface specification
• Oracle ListIterator Documentation — Bidirectional iterator interface
• Baeldung: Iterator vs Iterable — Understanding the difference between the two interfaces
• Java SE: For Each Loop — How the enhanced for loop works with collections

Conclusion

Iteration is where many Java collection performance issues surface in production. The core rule is simple: never modify a collection directly during iteration — use iterator.remove() or copy before iterating. The fail-fast mechanism catches some violations but not all, so defensive copying or explicit iterators are the reliable approach.

For most cases, an explicit Iterator with remove() is the clearest pattern. ListIterator is the right tool when you need backward traversal or positional modifications. Functional forEach() is clean for read-only operations but does not mix well with checked exceptions or mid-iteration mutations.

Iteration patterns apply to every collection type — HashMap, TreeMap, ArrayList, LinkedList, HashSet, TreeSet, and Queue/Deque all share the same underlying iterator contracts. Once iteration mechanics are solid, HashMap entry iteration and Queue processing patterns become straightforward to reason about.