Creating Custom Iterator in Java

1. Introduction

An Iterator<E> is an interface in the Java Collections framework and provides methods that allow traversing through a collection. An Iterator instance can be obtained by calling the iterator() method on a Collection, such as a List, Set, and traversing elements individually. An iterator has three core methods that aid in traversal:

• hasNext()
• next()
• remove()

In this tutorial, we’ll see how to introduce custom iterators and use them in our code.

2. The Need for Custom Iterators

Before we try to write our version of an iterator, let’s talk about the need to create one in the first place. Nearly all Collection interfaces, such as List and Set, have their version of iterators. We use these iterators regularly in code to satisfy our iteration needs:

@Test
public void givenListOfStrings_whenIteratedWithDefaultIterator() {
    List<String> listOfStrings = List.of("hello", "world", "this", "is", "a", "test");
    Iterator<String> iterator = listOfStrings.iterator();
    Assert.assertTrue(iterator.hasNext());
    Assert.assertEquals(iterator.next(), "hello");
}

The default versions of iterators are only meant to iterate through the underlying collection linearly. It goes from one element to the next using the next() method. We cannot use the default iterators to perform any additional operation on the elements. These are some of the reasons why we might want to implement our iterators:

• to iterate over a collection in a custom order
• to perform any additional operations on each element of the collection while traversing

3. Implementing a Custom Iterator

In this section, we’ll look at how we can implement our custom iterator. We can create a custom iterator for a List<String> collection or any custom object. In our example, we’ll use a simple Movie class:

public class Movie {
    private String name;
    private String director;
    private float rating;
    // standard getters and setters
}

3.1. Custom Iterator for Inbuilt Datatypes

Let’s consider we have a List of Strings. The default iterator() will only allow us to traverse through the given list from left to right. However, let’s say we want to only traverse through the elements of the list, which are palindrome in nature. A palindrome string is the same as its reverse.

Here we reach a limitation of the default iterator implementation, and we must develop our own. Given a list of strings, we hope to traverse through only the palindrome strings using our custom iterator.

We’ll call our iterator PalindromeIterator. The iterator must implement the Iterator<E> interface and provide an implementation of the abstract methods:

public class PalindromIterator implements Iterator<String> {
    @Override
    public boolean hasNext() {
        // Write custom logic
    }

    @Override
    public String next() {
        // Write custom logic
    }
}

Before we think about implementing the above methods, let’s write a basic method that takes in a String and returns whether it is a palindrome or not:

private boolean isPalindrome(String input) {
    for (int i = 0; i < input.length() / 2; i++) {
        if (input.charAt(i) != input.charAt(input.length() - i - 1)) {
            return false;
        }
    }
    return true;
}

We’ll use a currentIndex attribute to keep track of the iterator’s current position, and we’ll need a list attribute that holds our collection data.

Our definition of hasNext() should return true if there is at least another string in the collection, a palindrome. To do this, we continue to loop through the given list and check if we encounter a palindrome String. We do this by making a call to the isPalindrome() method we defined earlier:

@Override
public boolean hasNext() {
    while (currentIndex < list.size()) {
        String currString = list.get(currentIndex);
        if (isPalindrome(currString)) {
            return true;
        }
        currentIndex++;
    }
    return false;
}

The next() method will do the actual traversal of the elements in the list. We’ll increment the currentindex inside the method and return the element associated with it. However, we do this only if we are sure the collection has the next element to reach. Failing to do this might result in an IndexOutOfBoundsException. Similarly, if we reach the end of the list and there are no palindromes anymore, we throw a NoSuchElementException back to the caller:

@Override
public String next() {
    if (!hasNext()) {
        throw new NoSuchElementException();
    }
    return list.get(currentIndex++);
}

Let’s write a small test to see if it works:

@Test
public void givenListOfStrings_whenPalindromIterator_thenOnlyPalindromes() {
    List<String> listOfStrings = List.of("oslo", "madam", "car", "deed", "wow", "test");
    PalindromIterator palindromIterator = new PalindromIterator(listOfStrings);
    int count = 0;
    while(palindromIterator.hasNext()) {
        palindromIterator.next();
        count++;
    }
    assertEquals(count, 3);
}

3.2. Custom Iterator for a Custom Object

We can write iterators for a collection of a custom type as well. Let’s consider we have a List<Movie> for which we want to write our custom iterator. We want our iterator to only iterate through movies that have a rating of 8 and above:

private boolean isMovieEligible(Movie movie) {
    return movie.getRating() >= 8;
}

Keeping the above restriction in place, we write our definitions of next() and hasNext():

public class CustomMovieIterator implements Iterator<Movie> {
    private int currentIndex;
    private final List<Movie> list;

    public CustomMovieIterator(List<Movie> list) {
        this.list = list;
        this.currentIndex = 0;
    }

    @Override
    public boolean hasNext() {
        while (currentIndex < list.size()) {
            Movie currentMovie = list.get(currentIndex);
            if (isMovieEligible(currentMovie)) {
                return true;
            }
            currentIndex++;
        }
        return false;
    }

    @Override
    public Movie next() {
        if (!hasNext()) {
            throw new NoSuchElementException();
        }
        return list.get(currentIndex++);
        }
    }
}

Let’s also add a simple unit test to verify the iterator:

@Test
public void givenMovieList_whenMovieIteratorUsed_thenOnlyHighRatedMovies() {
    List<Movie> movies = getMovies();
    CustomMovieIterator movieIterator = new CustomMovieIterator(movies);
    int count = 0;
    while (movieIterator.hasNext()) {
        movieIterator.next();
        count++;
    }
    assertEquals(4, movies.size());
    assertEquals(2, count);
}

3.3. Custom Iterator for Custom Collections

We know that Java allows us to create a Collection of our own. For example, we can implement a version of the List<E> interface and name it MyList<E>. We can also define my versions of all the methods of the List interface, such as add(), remove(), size(), and isEmpty():

public class MyList<E> implements List<E> {
    @Override
    public int size() {
        // custom implementation
    }
    @Override
    public boolean isEmpty() {
        // custom implementation
    }
    @Override
    public boolean contains(Object o) {
        // custom implementation
    }
    @Override
    public boolean add(E e) {
        // custom implementation
    }
    @Override
    public boolean remove(Object o) {
        // custom implementation
    }
}

This also means we can provide my implementation of the iterator() and return an instance of a custom iterator which we have written specifically for our MyList<E>:

@Override
public Iterator<E> iterator() {
    return new MyListIterator();
}

private class MyListIterator implements Iterator<E> {
    @Override
    public boolean hasNext() {
        // custom implementation
    }

    @Override
    public E next() {
        // custom implementation
    }
}

It should be noted that the implementations of the methods have been omitted above for brevity. In our examples, we looked at overriding the next() and hasNext() methods. However, we can extend our custom iterators to override the remove() and forEachRemaining() methods.

4. Conclusion

In this article, we looked at how to create a custom iterator in Java and apply it to our collections. This gives us better control over how we iterate over the collections. While we provided examples on the List collection for the most part, this can be extended to other collections which implement the Iterable interface.

We also looked at how to write iterators for custom classes and collections.