You have a BookShelf that stores books in an ArrayList internally. You want callers to be able to iterate over books without knowing it’s an ArrayList. Next month you might change it to a linked list or a tree structure sorted by author. If callers work directly with your internal list, every change to your storage structure breaks them. The Iterator pattern gives callers a stable traversal interface that survives any change to the underlying data structure.

This is one of the patterns you already use every day through Java’s for-each loop. Every class that implements Iterable<T> is participating in this pattern. Understanding the mechanics helps you write cleaner custom collections and explains why certain traversal approaches are more maintainable than others.

Pattern Structure

• Iterator — declares hasNext() and next(). Callers use only this interface.
• Concrete Iterator — implements the traversal algorithm. Can maintain its own traversal state (current index, filter criteria).
• Aggregate (Collection) — declares a factory method that creates an Iterator. Hides internal storage.

Custom Iterator Implementation

package iterator;
public interface BookIterator {
    boolean hasNext();
    Book next();
}

package iterator;
public class Book {
    private final String title;
    private final String author;
    private final int year;
    public Book(String title, String author, int year) {
        this.title = title; this.author = author; this.year = year;
    }
    public int    getYear()  { return year; }
    public String getTitle() { return title; }
    @Override
    public String toString() { return "\"" + title + "\" by " + author + " (" + year + ")"; }
}

BookShelf exposes two factory methods that return different iterator types. The DecadeIterator is the interesting one — it applies filtering logic as part of traversal, which would be clunky to implement as an external loop.

package iterator;
import java.util.ArrayList;
import java.util.List;
public class BookShelf {
    private final List<Book> books = new ArrayList<>();
    public void addBook(Book book) { books.add(book); }
    public BookIterator iterator() {
        return new ForwardIterator();
    }
    /** Filtered iterator — only books published in the given decade (e.g. 2000 for 2000-2009) */
    public BookIterator iteratorByDecade(int decade) {
        return new DecadeIterator(decade);
    }
    // Inner classes have access to the outer list — no need to expose it
    private class ForwardIterator implements BookIterator {
        private int index = 0;
        @Override public boolean hasNext() { return index < books.size(); }
        @Override public Book    next()    { return books.get(index++); }
    }
    private class DecadeIterator implements BookIterator {
        private final int decade;
        private int index = 0;
        private Book nextBook;
        DecadeIterator(int decade) {
            this.decade = decade;
            advance();  // find the first matching book upfront
        }
        private void advance() {
            nextBook = null;
            while (index < books.size()) {
                Book b = books.get(index++);
                if (b.getYear() / 10 * 10 == decade) { nextBook = b; return; }
            }
        }
        @Override public boolean hasNext() { return nextBook != null; }
        @Override public Book    next()    { Book b = nextBook; advance(); return b; }
    }
}

public class Main {
    public static void main(String[] args) {
        BookShelf shelf = new BookShelf();
        shelf.addBook(new Book("Clean Code",               "Robert Martin", 2008));
        shelf.addBook(new Book("The Pragmatic Programmer", "Andrew Hunt",   1999));
        shelf.addBook(new Book("Effective Java",           "Joshua Bloch",  2001));
        shelf.addBook(new Book("Design Patterns",          "Gang of Four",  1994));
        shelf.addBook(new Book("Refactoring",              "Martin Fowler", 2018));
        shelf.addBook(new Book("Working Effectively with Legacy Code", "Feathers", 2004));
        System.out.println("-- All books --");
        BookIterator it = shelf.iterator();
        while (it.hasNext()) System.out.println("  " + it.next());
        System.out.println("\n-- Books from the 2000s --");
        BookIterator it2000s = shelf.iteratorByDecade(2000);
        while (it2000s.hasNext()) System.out.println("  " + it2000s.next());
    }
}

Console Output

How Java’s For-Each Loop Uses Iterator

The for-each loop is syntactic sugar. for (Book b : shelf) compiles to exactly this:

// What for-each compiles to:
Iterator<Book> it = shelf.iterator();  // calls Iterable.iterator()
while (it.hasNext()) {
    Book b = it.next();
    // loop body
}
// To make BookShelf work with for-each, implement Iterable<Book>:
public class BookShelf implements Iterable<Book> {
    @Override
    public Iterator<Book> iterator() {
        return books.iterator();  // delegate to the internal list's iterator
    }
}

Once BookShelf implements Iterable<Book>, it works natively with for-each, Stream.of(), and any method that accepts an Iterable.

Iterator in the JDK

java.util.Iterator and java.lang.Iterable are the JDK’s Iterator pattern. Every Collection is Iterable. Scanner implements Iterator<String> — you can iterate over lines of input like any collection. ResultSet in JDBC uses next() and cursor position — the Iterator pattern applied to database rows.

When to Use Iterator

Reach for Iterator when: you want to hide a collection’s internal structure from callers. You need multiple traversal algorithms over the same collection (forward, reverse, filtered). You want your collection to integrate naturally with Java’s for-each and Stream APIs. You’re building a library where clients should not depend on your specific collection implementation.

Avoid building custom iterators when: the collection is a standard java.util type — its built-in iterators already handle everything. The traversal is a one-off query better expressed as a Stream pipeline. You need concurrent access — standard iterators are not thread-safe; use concurrent collections or snapshot iterators instead.

Runnable Code on GitHub

Full source at ankurm.com/git.app/asmhatre/design-patterns under 03-behavioral/iterator/.

javac 03-behavioral/iterator/*.java -d out/iterator
java -cp out/iterator iterator.Main

See Also

• Composite Design Pattern in Java — iterating a tree is a natural use case for custom iterators that flatten recursive structure
• Visitor Design Pattern in Java — another way to traverse a structure without exposing internals, but adds per-type behaviour

Further Reading

• Iterator — Refactoring.Guru
• Design Patterns: Elements of Reusable Object-Oriented Software — Gamma et al., Chapter 5