Estimate project
← All posts

Stream Gatherers in action, Part 2

Our journey through Stream Gatherers, added in Java 22 via JEP 461, goes on – this time we turn to the built-in gatherers and look at what they can do.

8 min read
JavaFunctional Programminguncoverjavajava22stream gatherersstream

In this article we investigate Stream Gatherers, which arrived in Java 22 through JEP 461. We focus on the built-in gatherers and look at what they can do. We’ll also dig into building more complex operations by composing these built-in gatherers, showing the extra functionality and flexibility they add to Java’s Stream API. The goal of this exploration is to show where these powerful tools come in handy in stream processing and what they bring to the table.

A look at the built-in Gatherers

In this section we go through built-in gatherers such as fold, mapConcurrent, scan, windowFixed, and windowSliding, giving a short description of each and then showing it in action.

Fold

This Gatherer merges elements into one result while the stream is processed, much like Stream::reduce. The difference is that reduce wraps its result in an Optional, whereas Fold returns a stream holding the final aggregated value directly.

Take a simple example that computes a factorial:

System.out.println("Fold example:");
Stream.of(1, 2, 3, 4, 5)
       .gather(Gatherers.fold(() -> 1, (a, b) -> a * b))
       .forEach(System.out::println);

As shown, fold’s factory method accepts two arguments:

  • initial: a Supplier delivering the starting value of the folding operation
  • folder: a BiFunction used to combine elements one after another

Output:

Fold example:
120

Map Concurrent

The “Map Concurrent” operation lets functions run concurrently over stream elements, limited by a maximum concurrency level and backed by virtual threads, while keeping the stream’s order intact.

Here’s how to use it to double every element:

System.out.println("Map concurrent example:");
Stream.of(1, 2, 3, 4, 5)
       .gather(Gatherers.mapConcurrent(4, a -> a *2))
       .forEach(System.out::println);

The method accepts two parameters:

  • maxConcurrency: specifies the desired concurrency level.
  • mapper: the Function applied to every element

The output shows efficient parallel processing: each number is doubled and the original order is retained:

Map concurrent example:
2
4
6
8
10

Scan

This Gatherer carries out a Prefix Scan, building up results step by step with the given functions. It begins with an initial value obtained from a Supplier, and for every stream element a BiFunction is applied to the current and the next element. Each accumulated result is then emitted downstream, which makes it possible to dynamically produce a sequence of gradually accumulated values.

Let’s use the scan method to compute factorials again:

System.out.println("Scan example:");
Stream.of(1, 2, 3, 4, 5)
       .gather(Gatherers.scan(()->1, (a,b) -> a*b))
       .forEach(System.out::println);

In contrast to the fold method, scan makes the stream show every intermediate step of the computation, not only the end result:

Scan example:
1
2
6
24
120

Window Fixed

It arranges stream elements into consecutive, ordered groups of a fixed size. An empty stream produces no windows. The last window may contain fewer elements when the total number of elements in the stream isn’t evenly divisible by the window size.

Here’s an example that splits the stream elements into windows of two elements each:

System.out.println("Window fixed example:");
Stream.of(1, 2, 3, 4, 5)
       .gather(Gatherers.windowFixed(2))
       .forEach(System.out::println);

We get the following output:

Window fixed example:
[1, 2]
[3, 4]
[5]

What we notice is that the last group holds just a single element, because the stream has an odd number of elements, which can’t be split evenly by a window size of two.

Window Sliding

The “Window Sliding” Gatherer splits elements into dynamically overlapping windows of a given size. Every new window moves one element forward relative to the preceding one, keeping the data flowing continuously. What sets this operation apart is that it produces multiple overlapping windows, so certain elements show up in successive windows, giving a complete picture of the stream’s sequence.

Let’s run the windowSliding operation on the same stream as earlier:

System.out.println("Window sliding example:");
Stream.of(1, 2, 3, 4, 5)
       .gather(Gatherers.windowSliding(2))
       .forEach(System.out::println);

Now the output looks like this:

Window sliding example:
[1, 2]
[2, 3]
[3, 4]
[4, 5]

This time we see more windows, each holding two elements. Note that some elements appear in two successive windows.

Built-in Gatherers in action

Now that we understand how the built-in gatherers work, let’s use them to solve more practical problems: guaranteeing a safe arrangement of animals, simulating games between players, and keeping track of a bank account’s balance history.

Safe arrangement of animals

To tackle the safe animal arrangement problem, we look at a sequence made up of three kinds of animals:

  • wolf,
  • sheep,
  • sheepdog.

The key rule is that no three consecutive animals may include a wolf and a sheep unless a sheepdog is there to protect it, since otherwise the sheep is in danger. We want to implement validation logic that checks whether a stream of animals satisfies this rule. As a first step, we model the animal types with an enum, laying the groundwork for the logic.

public enum Animal {
   SHEEP, SHEEP_DOG, WOLF
}

Next, we’ll build a Gatherer that wraps this validation logic:

public class AnimalStreamUtils {

   public static Gatherer<Animal, ?, Boolean> isValidSequence() {
       Predicate<List<Animal>> validTriplePredicate = triple -> !(
               triple.contains(SHEEP) && triple.contains(WOLF) && !triple.contains(SHEEP_DOG)
       );

       var tripleWindowGatherer = Gatherers.<Animal>windowSliding(3);
       var areAllTriplesValidGatherer = Gatherers.<List<Animal>, Boolean>fold(
               () -> true,
               (result, triple) -> result && validTriplePredicate.test(triple)
       );

       return tripleWindowGatherer.andThen(areAllTriplesValidGatherer);
   }
}

Key points:

  • AnimalStreamUtils: a utility class exposing a factory method that makes plugging in the Gatherer simpler and more convenient.
  • validTriplePredicate: checks each triple to confirm it is safe, ruling out situations in which a wolf could threaten a sheep.
  • tripleWindowGatherer: produces consecutive triples of animals to be analyzed, so that the whole sequence is evaluated.
  • areAllTriplesValidGatherer: confirms that every triple of animals is safe according to the defined criteria.
  • Gatherer:andThen: this method merges gatherers into a single one: \
    stream.gather(a.andThen(b)) does the same as stream.gather(a).gather(b).

With the Gatherer in place, let’s move on to testing how it works.

var validSequence = List.of(SHEEP, SHEEP_DOG, WOLF, WOLF);
System.out.println("Valid animal sequence result:");
validSequence.stream()
       .gather(AnimalStreamUtils.isValidSequence())
       .forEach(System.out::println);

var invalidSequence = List.of(SHEEP_DOG, SHEEP, WOLF, WOLF);
System.out.println("\nInvalid animal sequence result:");
invalidSequence.stream()
       .gather(AnimalStreamUtils.isValidSequence())
       .forEach(System.out::println);

Running it gives us the expected output:

Valid animal sequence result:
true
Invalid animal sequence result:
false

Simulating games

On to the next problem: we want to pair up players and simulate games between them. Each game ends with one of the players winning or with a draw.

We start with a simple Player model that holds nothing but a name, used to identify each player in the simulated games:

public record Player(String name) {
}

Then we add a Game interface with two separate implementations: CompletedGame, standing for a game that finished successfully, and InvalidGame, used when there weren’t enough players.

public interface Game {
   Game INVALID_GAME = new InvalidGame();
   static Game completedGame(Player player1, Player player2, GameResult result) {
       return new CompletedGame(player1, player2, result);
   }
}

record CompletedGame(Player player1, Player player2, GameResult result) implements Game {
}

class InvalidGame implements Game {
   @Override
   public String toString() {
       return "INVALID GAME";
   }
}

GameResult is an enum describing the possible outcomes: one of the players wins, or the game is drawn. It also provides a method that produces a random result for each game.

public enum GameResult {
   PLAYER1_WON, PLAYER2_WON, DRAW;

   private static final Random RANDOM = new Random();
   public static GameResult randomResult() {
       return switch (RANDOM.nextInt(3)) {
           case 0 -> PLAYER1_WON;
           case 1 -> PLAYER2_WON;
           default -> DRAW;
       };
   }
}

After that, we build a Gatherer that pairs players up and runs their games, taking care of the whole matchmaking process.

public class GameGatherers {

   public static Gatherer<Player, ?, Game> performGamesGatherer() {
       Gatherer<Player,?, List<Player>> pairPlayersGatherer = Gatherers.windowFixed(2);
       Gatherer<List<Player>,?, Game> simulateGamesGatherer = Gatherers.mapConcurrent(4, players -> {
           if(players.size() != 2) {
               return Game.INVALID_GAME;
           }
           return Game.completedGame(players.get(0), players.get(1), GameResult.randomResult());
       });

       return pairPlayersGatherer.andThen(simulateGamesGatherer);
   }
}

Key points:

  • pairPlayersGatherer: puts players into pairs so that each of them plays in just one game, relying on windowFixed to handle the matchups.
  • simulateGamesGatherer: simulates the games between paired players. When there aren’t enough players to form a pair, it returns INVALID_GAME. Otherwise, it creates a game with a random result.
  • andThen: lastly, we combine both gatherers to get the intended result.

Now let’s see the Gatherer at work:

var listOfPlayers = List.of(
       new Player("John"),
       new Player("Marry"),
       new Player("George"),
       new Player("Ann"),
       new Player("Pete"),
       new Player("Stuart"),
       new Player("Adam")
);

System.out.println("\nGames result:");
listOfPlayers.stream()
       .gather(GameGatherers.performGamesGatherer())
       .forEach(System.out::println);

This produces the following output:

Games result:
CompletedGame[player1=Player[name=John], player2=Player[name=Marry], result=PLAYER2_WON]
CompletedGame[player1=Player[name=George], player2=Player[name=Ann], result=DRAW]
CompletedGame[player1=Player[name=Pete], player2=Player[name=Stuart], result=DRAW]
INVALID GAME

The final game is flagged as invalid because the number of players is odd, which shows how our setup deals with cases where not everyone can be paired.

Bank account balance history

For the last task, we return to the Money record first introduced in our opening article on Stream Gatherers.

public record Money(BigDecimal amount, Currency currency) {
   public Money add(Money money) {
       return new Money(money.amount.add(this.amount), currency);
   }

   public Money multiply(BigDecimal multiplier) {
       return new Money(amount.multiply(multiplier), currency);
   }
}

Treating Money as the representation of both a bank account balance and transactions, we want to follow how the balance changes over a series of transactions. The answer is to write a Gatherer, shown below, that efficiently applies the effect of each transaction to the starting balance.

public class MoneyUtils {

   public static Gatherer<Money, ?, Money> computeBalanceHistory(Money balance){
       return Gatherers.scan(() -> balance, Money::add);
   }
}

The key elements are:

  • The starting balance, passed to the computeBalanceHistory method, is where the calculation begins.
  • The Gatherers::scan function updates the balance with every transaction in the stream, mirroring the financial changes.

Let’s now try the Gatherer out:

var transactions = List.of(
       new Money(BigDecimal.valueOf(-10), PLN),
       new Money(BigDecimal.valueOf(20), PLN),
       new Money(BigDecimal.valueOf(50), PLN)
);

var balance = new Money(BigDecimal.valueOf(270), PLN);

System.out.println("\n Balance history:");
transactions.stream()
       .gather(MoneyUtils.computeBalanceHistory(balance))
       .forEach(System.out::println);

Here are the results:

Balance history:
Money[amount=260, currency=PLN]
Money[amount=280, currency=PLN]
Money[amount=330, currency=PLN]

Short as this solution may look, it can prove handy in many use cases.

Summary

In this follow-up article on Stream Gatherers, we took a closer look at built-in functionality such as fold, mapConcurrent, scan, windowFixed, and windowSliding. We started with an overview and then used these gatherers to solve more practical problems, showing how usable they are. Getting the desired results frequently meant deliberately combining several gatherers with the andThen method, which highlights how flexible and useful these powerful stream processing tools are.

Gatherers are clearly intended for building tailored solutions, yet their built-in features also open up valuable possibilities for stream operations, making stream handling simpler and better.

We’d love to hear your opinion on these built-in gatherers. Are they useful to you? Is there any functionality you think is lacking?