How Does Streams API Work? A Deep Dive on Stream Operation Flow

We know what are Streams from the previous article I posted - Introduction to Java Streams API.

Let us deep-dive into Streams API, know how they function.

How Stream API Works?

A Java Stream is composed of 3 main phases.

1. Source: Data is collected from a collection, we usually call it Stream source, for example:

   • List
   • Map
   • Set
   • Array, etc.

2. Intermediate Operations: Every operation in the pipeline is applied to each element in a sequence. This series of operations is called Intermediate Operations, for example:

   • filter(predicate)
   • sorted()
   • distinct()
   • map(), etc.

3. Terminal: This means we are terminating/completing the stream operation, for example:

   • count()
   • collect(), etc.

Note: When defining a stream, we are just declaring the steps to follow a pipeline of operations, they won’t get executed until we call our terminal operation.

Intermediate operations

Intermediate operations return a new stream.

They are always lazy, executing an intermediate operation such as filter() does not actually perform any filtering, but instead creates a new stream, when traversed, contains the elements of the initial stream that match the given predicate.

Traversal of the pipeline source does not begin until the terminal operation of the pipeline is executed.

Intermediate operations are further divided into stateless and stateful operations.

1. Stateless operations: The filter and map retain no state from previously seen elements when processing a new element. Each element can be processed independently of operations on other elements. Stateful operations, such as distinct and sorted, may incorporate states from previously seen elements when processing new elements.

2. Stateful operations: This may need to process the entire input before producing a result. For example, one cannot produce any results from sorting a stream until one has seen all elements of the stream. As a result, under parallel computation, some pipelines containing stateful intermediate operations may require multiple passes on the data or may need to buffer significant data. Pipelines containing exclusively stateless intermediate operations can be processed in a single pass, whether sequential or parallel, with minimal data buffering.

Terminal operations

Terminal operations, such as Stream.forEach(...) or IntStream.sum(...), may traverse the stream to produce a result or a side-effect.

After the terminal operation is performed, the stream pipeline is considered consumed, and can no longer be used. If you need to traverse the same data source again, you must return to the data source to get a new stream.

In almost all cases, terminal operations are eager, completing their traversal of the data source and processing of the pipeline before returning. Only the terminal operations iterator() and spliterator() are not; these are provided as an “escape hatch” to enable arbitrary client-controlled pipeline traversals in the event that the existing operations are not sufficient for the task.

Code

In my previous article we have seen an example with intermediate operations, now let us see example without intermediate operations.

Book is a POJO with a constructor, getters, and setters.

class Book {
  String title;
  String author;
  Integer year;
  Integer copiesSoldInMillions;
  Double rating;
  Double costInEuros;

  public Book(String title, String author, Integer year, Integer copiesSoldInMillions, Double rating, Double costInEuros) {
    this.title = title;
    this.author = author;
    this.year = year;
    this.copiesSoldInMillions = copiesSoldInMillions;
    this.rating = rating;
    this.costInEuros = costInEuros;
  }

  public String getAuthor() {
    return author;
  }

  public Integer getCopiesSoldInMillions() {
    return copiesSoldInMillions;
  }

  @Override
  public String toString() {
    return "Book{" +
      "title='" + title + '\'' +
      ", author='" + author + '\'' +
      ", year=" + year +
      ", copiesSoldInMillions=" + copiesSoldInMillions +
      ", rating=" + rating +
      ", costInEuros=" + costInEuros +
      '}';
  }
}

Another class BookDatabase for dummy data injection.

import java.util.Arrays;
import java.util.List;

public class BookDatabase {
  public static List<Book> getAllBooks() {
    return Arrays.asList(
      new Book("Don Quixote", "Miguel de Cervantes", 1605, 500, 3.9, 9.99),
      new Book("A Tale of Two Cities", "Charles Dickens", 1859, 200, 3.9, 10.0),
      new Book("The Lord of the Rings", "J.R.R. Tolkien", 2001, 150, 4.0, 12.50),
      new Book("The Little Prince", "Antoine de Saint-Exupery", 2016, 142, 4.4, 5.0),
      new Book("The Dream of the Red Chamber", "Cao Xueqin", 1791, 100, 4.2, 10.0)
    );
  }
}

And finally out BookApplication class that does the declarative programming or immutability on each book object.

import java.util.Map;
import java.util.stream.Collectors;

public class BookApplication {
  public static void main(String[] args) {
    Map<String, Integer> bookSold =
      BookDatabase.getAllBooks()
        .stream()
        .collect(Collectors.toMap(Book::getAuthor, Book::getCopiesSoldInMillions));

    System.out.println(bookSold);
  }
}

If we imagine Streams as streams of water flowing through a tank, then our job is to make use of each byte that gets out of the tank through the pipe with Stream API methods.