Break or return from Java 8 stream forEach?

Stream API was introduced by Java 8 for processing collections of data by a powerful and expressive way. One common question that arises when using streams is: What do I need to do to break out of, or return from, a forEach operation?

In traditional loops you can break or return early. But the forEach method in streams doesn't make this easy. This article examines why this is the case and examines alternate ways for early termination in the stream processing system.

Read More: Java Stream API Improvements.

Understanding Stream forEach

The forEach method is a terminal operation, which runs action on each element of the stream. It's meant to process each element; it doesn't allow early exit by break or return.

List names = Arrays.asList("Alice", "Bob", "Charlie");
names.stream().forEach(name -> {
    System.out.println(name);
});

The forEach in the example above prints each name in the list. But what if we actually wanted to stop processing whenever we saw "Bob"?

What's Wrong with us Not using break or return?

The forEach does not use traditional loop so it does not allow to use break or continue statement in lambda expression inside of it. Like return inside lambda exits the lambda expression but not the forEach or the enclosing method. Attempting to use break or continue will result in a compilation error:

names.stream().forEach(name -> {
    if (name.equals("Bob")) {
        break; // Compilation error
    }
});

Alternative Approaches

1. Use a Regular for Loop

But if you want to break out of a loop a classic for loop is a valid and very often the best option.

for (String name : names) {
    if (name.equals("Bob")) {
        break;
    }
    System.out.println(name);
}

2. Use anyMatch or noneMatch

The anyMatch() method implies that the stream processing is short circuited when a condition is satisfied.

boolean found = names.stream().anyMatch(name -> {
    if (name.equals("Bob")) {
        // Perform action
        System.out.println("Found Bob");
        return true; // This will short-circuit the stream
    }
    System.out.println(name);
    return false;
});

3. Use takeWhile for that (Java 9 and Above)

If you're using Java 9 or above you can use the takeWhile method to process elements until some condition is met.

names.stream()
     .takeWhile(name -> !name.equals("Bob"))
     .forEach(System.out::println);

4. Here you should use an Exception (Not Recommended)

You can technically throw an exception in the case that you want to exit the forEach method, however this is not recommended.

try {
    names.stream().forEach(name -> {
        if (name.equals("Bob")) {
            throw new RuntimeException("Exit loop");
        }
        System.out.println(name);
    });
} catch (RuntimeException e) {
    // Handle exception
}

5. Use a Custom Spliterator

More control over stream processing is had with a custom Spliterator, at the cost of increased complexity.

Choosing the Right Approach

• Simplicity: In case early exit is required, the traditional loop is easy.
• Functional Style: If you don't want to stray from the functional paradigm, you might prefer anyMatch, noneMatch, takeWhile (Java 9+) methods.
• Performance: Think of each method in regard to its performance implications, especially with large datasets.

Conclusion

The forEach method in Java 8 streams doesn't allow you to break or return the way you would in the traditional sense, but there are ways to work around it. This knowledge helps you pick the best approach for your business scenario.