Stream API

It is 9 p.m. and a food delivery app has handled three hundred orders today. The manager asks a simple question: "What did we earn from delivered orders over ₹200, sorted from biggest to smallest?" With plain loops you would write a counter, an if, a temporary list and a sort call, and the actual question would hide inside all that code.

The Stream API lets you write the question almost as you would say it: take the orders, keep the delivered ones, keep those over 200, pick the amounts, sort them, collect them. Below you will learn how a stream pipeline is built, why nothing runs until the very end, and which mistakes trip up most beginners.

What is the Stream API?

Keep three facts in mind:

• A stream is not a data structure. It stores nothing; it only carries elements from a source.
• A stream never changes its source. Filtering a stream of orders leaves the original list untouched.
• A stream can be used only once. After the terminal operation it is closed.

Why is the Stream API used?

Loops tell the computer how to do something, step by step. Streams let you describe what you want, and the library handles the looping.

• Readable code. Each operation has a clear name, so the pipeline reads like a sentence.
• Fewer bugs. No index counters, no temporary lists, no forgotten break.
• Easy to change. Adding one more condition is one more filter line.
• Built-in helpers. Grouping, counting, summing, averaging and joining text are ready-made collectors.
• Parallel option. For large, CPU-heavy jobs, parallelStream() can split the work across cores.

Streams also pair naturally with lambda expressions, which is where most of their short, expressive style comes from.

Real-Life Example

Think of the packing counter in a cloud kitchen. Finished orders arrive on a conveyor belt, one at a time. The first worker removes any order marked "cancelled". The second worker sticks a price label on each box. The last worker at the end of the belt puts the boxes into delivery bags.

Here is the interesting part: the belt does not start moving until someone is standing at the end to receive the boxes. There is no point packing orders that nobody will collect.

In stream terms, the conveyor belt is the stream, the pile of orders is the source, the first two workers are intermediate operations, and the bagging worker is the terminal operation. The belt waiting for someone at the end is called laziness.

java
import static java.util.stream.Collectors.toList;

List<R> result = source.stream()   // source
        .filter(x -> condition)    // intermediate
        .map(x -> newValue)        // intermediate
        .sorted()                  // intermediate
        .collect(toList());        // terminal

How the Stream API Works

Every stream follows the same shape: one source, zero or more intermediate operations, and exactly one terminal operation.

text
orders.stream()     source
      |
      v
.filter(delivered)  lazy
      |
      v
.map(amount)        lazy
      |
      v
.collect(toList())  runs all
      |
      v
[250, 180, 420]

Intermediate operations do not process anything when you call them. Each one just adds a stage to a plan and returns a new stream. Only when the terminal operation is called does data begin to flow. Even then, Java does not filter the whole list first and map it afterwards. It pushes one element through every stage, then the next element, and so on. Because of this, limit(2) or findFirst() can stop the pipeline early, and the remaining elements are never touched.

There are two kinds of intermediate operations. Stateless ones like filter and map look at one element at a time. Stateful ones like sorted and distinct must see every element before they can pass anything on.

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

import static java.util.stream.Collectors.toList;

public class DeliveryTotals {
    static class Order {
        String dish; int amount; boolean delivered;
        Order(String d, int a, boolean ok) {
            dish = d; amount = a; delivered = ok;
        }
    }

    public static void main(String[] args) {
        List<Order> orders = Arrays.asList(
                new Order("Biryani", 320, true),
                new Order("Dosa", 140, true),
                new Order("Thali", 260, false),
                new Order("Paneer roll", 210, true),
                new Order("Pizza", 450, true));

        List<Integer> big = orders.stream()
                .filter(o -> o.delivered)
                .filter(o -> o.amount > 200)
                .map(o -> o.amount)
                .sorted((a, b) -> b - a)
                .collect(toList());
        System.out.println("Big orders: " + big);

        int earned = orders.stream()
                .filter(o -> o.delivered)
                .mapToInt(o -> o.amount)
                .sum();
        System.out.println("Earned: Rs " + earned);
        System.out.println("Orders in list: " + orders.size());
    }
}

text
Big orders: [450, 320, 210]
Earned: Rs 1120
Orders in list: 5

java
import java.util.Arrays;
import java.util.List;
import java.util.stream.Stream;

import static java.util.stream.Collectors.toList;

public class LazyKitchen {
    public static void main(String[] args) {
        List<String> dishes = Arrays.asList(
                "Idli", "Poha", "Upma", "Vada", "Kheer");

        Stream<String> plan = dishes.stream()
                .filter(d -> {
                    System.out.println("check " + d);
                    return !d.equals("Poha");
                });
        System.out.println("Plan ready, nothing ran");

        List<String> firstTwo = plan
                .map(d -> {
                    System.out.println("pack  " + d);
                    return d.toUpperCase();
                })
                .limit(2)
                .collect(toList());
        System.out.println(firstTwo);
    }
}

text
Plan ready, nothing ran
check Idli
pack  Idli
check Poha
check Upma
pack  Upma
[IDLI, UPMA]

java
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;

import static java.util.stream.Collectors.groupingBy;
import static java.util.stream.Collectors.joining;
import static java.util.stream.Collectors.summingInt;

public class RestaurantReport {
    static class Order {
        String place; String dish; int amount;
        Order(String p, String d, int a) {
            place = p; dish = d; amount = a;
        }
    }

    public static void main(String[] args) {
        List<Order> orders = Arrays.asList(
                new Order("Spice Hut", "Korma", 280),
                new Order("Dosa Point", "Dosa", 120),
                new Order("Spice Hut", "Naan", 60),
                new Order("Dosa Point", "Vada", 90));

        Map<String, Integer> totals = orders.stream()
                .collect(groupingBy(o -> o.place,
                        TreeMap::new,
                        summingInt(o -> o.amount)));
        totals.forEach((place, sum) ->
                System.out.println(place + ": Rs " + sum));

        String menu = orders.stream()
                .map(o -> o.dish)
                .distinct()
                .collect(joining(", "));
        System.out.println(menu);
    }
}

text
Dosa Point: Rs 210
Spice Hut: Rs 340
Korma, Dosa, Naan, Vada

Common Mistakes

• Forgetting the terminal operation. A pipeline with only filter and map does nothing at all, so side effects inside it never happen.
• Using `Stream.toList()` on older Java. It arrived in Java 16. On Java 11, collect with Collectors.toList() instead.
• Changing the source inside the pipeline. Adding to or removing from the list while streaming it can throw ConcurrentModificationException.
• Reaching for `parallelStream()` by default. For small lists, the cost of splitting work is bigger than the gain.
• Putting heavy logic in `peek` or `forEach`. Keep lambdas short and free of side effects so the pipeline stays easy to read.

Interview Questions

Summary

• A stream is a one-time pipeline over a source; it never stores or changes data.
• The shape is always source, then intermediate operations, then one terminal operation.
• Intermediate operations are lazy and run only when the terminal operation is called.
• Elements travel through all stages one at a time, so limit and findFirst can stop early.
• Collect results with Collectors.toList(), groupingBy, summingInt and joining.
• Use mapToInt for number streams with handy methods like sum and average.

Related Topics

• Lambda Expressions: the short functions you pass to filter and map.
• Method References: a shorter way to write many stream lambdas.
• Optional: what findFirst and max return.
• Collection Framework: the sources most streams start from.