Iterator Pattern

1The problem it solves#

Start with the pain, because the pattern only makes sense once you feel it.

• Say I hand you a Playlist. Internally it might be an array, a linked list, or a tree sorted by play count.
• You want to loop over the songs. How?
• The naive answer: expose the internal list. Add a getSongs() that returns the raw ArrayList, and the caller writes a normal for loop.

That looks fine for about ten seconds. Here is what it actually costs:

• Storage leaks into the caller. They now know I use an ArrayList. Switch to a tree tomorrow and their code breaks. One storage change, N call sites to fix.
• Your internals are mutable from the outside. Anyone can grab that list and call .clear(). You handed out your private state.
• Every collection becomes its own dialect. Three collections stored three ways (songs, playlists, podcasts) means the caller learns three traversal styles.

The deeper problem is that two jobs got tangled together.

• Traversal logic and storage logic are now mixed.
• That is an encapsulation leak, and it breaks the Single Responsibility Principle: the caller is suddenly responsible for both reading data and knowing the layout.
• I want to let people walk my collection without telling them how it is built, and without letting them poke at my guts.

That is the gap. The Iterator pattern fills it.

2The idea (mental model)#

Here is how I explain it at the whiteboard.

• A collection is a book. An iterator is a bookmark.
• The book does not know where you are in it. The bookmark does.
• Two bookmarks can sit in the same book on different pages, and neither confuses the other.

So instead of the caller managing an index, I hand them a small object whose entire job is "remember where we are and give me the next item." Two methods:

• hasNext(): is there anything left?
• next(): give me the next thing, and move the bookmark forward.

What that buys you:

• The caller never sees the array, the index, or the node pointers.
• They just keep asking "got more?" and "give me the next one" until the answer is no.
• The collection stays sealed. The traversal state lives in a separate, throwaway object.

Storage is the collection's business. Position is the iterator's business. Mix them and the pattern is gone.

3Structure#

There are four roles, and naming them cleanly is half the interview.

• Iterator (interface): declares hasNext() and next().
• ConcreteIterator: implements it and holds the cursor state for one specific collection.
• IterableCollection (the aggregate, an interface): declares something like createIterator().
• ConcreteCollection: implements createIterator() and knows how to build the right iterator for its own layout.

Why a separate object and not a method on the collection:

• The collection hands out a fresh iterator every time.
• Each one tracks its own position, so there is no shared state and no bug when two parts of your code iterate the same collection.
• This is programming to an interface, not an implementation: the caller depends on Iterator, never on PlaylistIterator.

4Implementation in Java#

I will build the playlist, kept tight so the design shows through.

public interface Iterator<T> {
    boolean hasNext();
    T next();
}

public interface IterableCollection<T> {
    Iterator<T> createIterator();
}

The collection. The internal storage is an ArrayList, and nobody outside gets to see it.

public class Playlist implements IterableCollection<Song> {
    private final List<Song> songs = new ArrayList<>();

    public void add(Song song) {
        songs.add(song);
    }

    @Override
    public Iterator<Song> createIterator() {
        return new PlaylistIterator(songs);
    }
}

The iterator. This is the object that holds the cursor, and the only object that does.

public class PlaylistIterator implements Iterator<Song> {
    private final List<Song> songs;
    private int position = 0;

    public PlaylistIterator(List<Song> songs) {
        this.songs = songs;
    }

    @Override
    public boolean hasNext() {
        return position < songs.size();
    }

    @Override
    public Song next() {
        if (!hasNext()) {
            throw new NoSuchElementException("No more songs");
        }
        return songs.get(position++);
    }
}

The caller. Clean, and completely blind to how Playlist stores anything.

Playlist playlist = new Playlist();
playlist.add(new Song("Midnight City"));
playlist.add(new Song("Teardrop"));

Iterator<Song> it = playlist.createIterator();
while (it.hasNext()) {
    Song song = it.next();
    System.out.println(song.getTitle());
}

5A real-world example#

You have used this a thousand times. Java's java.util.Iterator is exactly this pattern.

• Every enhanced for loop is sugar over it:

for (Song song : playlist) { ... }

• The compiler calls iterator() under the hood and drives hasNext() and next() for you.
• That is why you loop over an ArrayList, a HashSet, and a LinkedList with identical syntax even though their internals are wildly different (array, hash buckets, node pointers). One loop body, three storage layouts.

Where it earns its keep in real systems:

• Paginated API clients. You write for (Record r : client.allRecords()) while the iterator quietly fetches page 2 only after you exhaust page 1. Lazy loading hides inside next() and the caller never thinks about pages.
• Database result sets. A ResultSet cursor is an iterator over rows you have not loaded yet. Stream a million rows without a million rows sitting in heap.
• Tree and graph traversal. In a file-system explorer you can expose a DepthFirstIterator and a BreadthFirstIterator over the same directory tree. Same collection, two walk orders, same loop body.

6When to use it, and when not to#

Reach for it when:

• You want to hide how a collection is stored but still let people walk it.
• You need more than one way to traverse the same structure: forward, reverse, filtered, shuffled.
• You are building a custom collection and want it to feel native, so make it Iterable and it drops into a for-each.
• Traversal should be lazy, computing or fetching the next item only when asked.

Skip it when:

• You are working with a plain List or Map that already gives you iteration. Do not wrap ArrayList in your own iterator class to look clever. The standard library already solved this.
• The collection is tiny, private, and only you touch it. A direct index loop is fine.

Rule of thumb I use:

• If the collection crosses a module or API boundary, an iterator is probably worth it.
• If it stays inside one class, usually not. The pattern is about boundaries, and with no boundary there is no payoff.

7Common mistakes#

Calling next() without checking hasNext().

• You blow past the end and either get an exception or, worse, silently return garbage.
• Always guard next() so it throws clearly when empty.
• That is why the example throws a NoSuchElementException with a message, on purpose.

Leaking the collection through the iterator (the classic gotcha).

• PlaylistIterator holds a reference to the same songs list.
• Add items to the playlist mid-iteration and behavior gets weird.
• Java's built-in iterators defend this with fail-fast checks that throw ConcurrentModificationException.
• For an interview, name the two fixes: snapshot a copy at createIterator() time, or track a modification count and detect the change. Do not ignore it.

Putting traversal state on the collection instead of the iterator.

• The anti-pattern: a private int currentIndex on Playlist itself, with first() and next() methods on the collection.
• Now you can only have one traversal at a time, and two loops over the same collection stomp on each other.
• The whole point is that state lives in the iterator, so each loop gets its own cursor.

Making the iterator do too much.

• It walks and returns. That is it.
• It should not filter, sort, and transform all at once unless that is literally its named job.
• Keep hasNext and next simple.

Forgetting to implement Iterable in Java.

• If you build a custom collection, implement java.lang.Iterable so it works with for-each.
• Rolling your own createIterator() when the language hands you iterator() for free just means your collection will not play nicely with the rest of Java.

8Where it shows up in interviews#

Iterator rarely shows up as "design an iterator." It hides inside a bigger problem, and the interviewer watches whether you reach for it naturally.

• "Design an in-memory collection or custom list." The follow-up is always "how do people loop over it?" The right answer is make it Iterable.
• "Design a file system." Offer different traversal orders as iterators. That earns points.
• "Design a card game or deck." Dealing cards one at a time is basically next().
• As a building block in other patterns. Composite pairs with it constantly (you iterate a tree of nodes). Observer sometimes iterates its subscribers.

If you are asked directly, run this order:

• Start with the mental model: the collection is the book, the iterator is the bookmark.
• Write the two interfaces, then the concrete pair.
• State up front that traversal state lives in a separate object, not the collection, and say why.

That one sentence tells the interviewer you understand the pattern instead of memorizing it. This is an Easy pattern, so the bar is not "can you write it." The bar is "do you know why it exists." Lead with the why.

Next, look at the Composite pattern (iterators walk composite trees beautifully) and the Observer pattern, where you will often iterate a list of subscribers.