Streams API

Filter, map, reduce — Java's functional pipeline for collections. When streams are clearer than loops, and when they aren't.

Loops, but declarative

Before streams, processing a collection in Java meant explicit loops:

List<String> activeNames = new ArrayList<>();
for (User u : users) {
    if (u.isActive()) {
        activeNames.add(u.getName().toUpperCase());
    }
}
Collections.sort(activeNames);

With streams (Java 8+):

List<String> activeNames = users.stream()
    .filter(User::isActive)
    .map(User::getName)
    .map(String::toUpperCase)
    .sorted()
    .toList();

The stream version describes WHAT you want — active users' names, uppercased, sorted. The loop version describes HOW step by step. Both produce the same result.

Streams aren't always better. For simple operations on small collections, a plain loop is often clearer. But for multi-step pipelines, especially anything involving filter/transform/group/sort, streams win on readability once you're used to them.

This chapter covers the pipeline mental model, the main operations, and the practical limits.

The pipeline mental model

A stream has three parts:

**Zero or more intermediate operations.** filter, map, sorted, distinct, limit, skip, flatMap, peek. Each returns a new Stream. They're **lazy** — they don't actually process anything until a terminal operation triggers the work.

**Exactly one terminal operation.** collect, count, forEach, reduce, findFirst, anyMatch, toList() (Java 16+). The terminal op consumes the stream and produces a result.

**Streams are single-use.** Once you've called a terminal operation, the stream is exhausted. You can't go back to the start:

Stream<String> s = list.stream();
s.count();         // 5
s.count();         // IllegalStateException — stream already used

If you need the same source twice, call .stream() twice on the original collection.

Common intermediate operations

**filter(Predicate)** — keep elements that match:

users.stream().filter(u -> u.getAge() >= 18)

**map(Function)** — transform each element:

users.stream().map(User::getName)   // Stream<User> → Stream<String>

**flatMap(Function)** — transform each element into a stream, then flatten:

List<List<String>> roles = ...;
roles.stream().flatMap(List::stream)   // Stream<List<String>> → Stream<String>

orders.stream().flatMap(o -> o.getItems().stream())   // all items across all orders

flatMap is the operation people miss most often. Use it whenever you have a stream of collections and want a stream of their elements.

**distinct()** — remove duplicates (using .equals()).

**sorted()** / **sorted(Comparator)** — sort. With no argument, requires elements to be Comparable.

**limit(n) / skip(n)** — take first n / skip first n. Often used together for pagination.

**peek(Consumer)** — perform a side effect without consuming. Mostly useful for debugging:

users.stream()
    .filter(User::isActive)
    .peek(u -> log.debug("checking {}", u))
    .map(User::getName)
    .toList();

Don't use peek for real side effects in production code — the rules around when it runs are unintuitive.

Common terminal operations

**toList()** (Java 16+) — collect into an unmodifiable List:

List<String> names = users.stream().map(User::getName).toList();

This replaced the older .collect(Collectors.toList()). Modern code uses .toList().

**collect(Collector)** — flexible collection into various shapes:

// Set
Set<String> nameSet = users.stream().map(User::getName).collect(Collectors.toSet());

// Map by key
Map<Long, User> byId = users.stream().collect(Collectors.toMap(User::getId, u -> u));

// Group by attribute
Map<String, List<User>> byRole = users.stream()
    .collect(Collectors.groupingBy(User::getRole));

// Count by attribute
Map<String, Long> countByRole = users.stream()
    .collect(Collectors.groupingBy(User::getRole, Collectors.counting()));

// Join into a single string
String joined = users.stream().map(User::getName)
    .collect(Collectors.joining(", "));

**count()** — number of elements:

long activeCount = users.stream().filter(User::isActive).count();

**anyMatch / allMatch / noneMatch** — short-circuit boolean checks:

boolean hasAdmin = users.stream().anyMatch(u -> u.hasRole("ADMIN"));
boolean allActive = users.stream().allMatch(User::isActive);

These short-circuit — anyMatch stops as soon as it finds a match.

**findFirst / findAny** — return an Optional containing one element:

Optional<User> admin = users.stream().filter(u -> u.hasRole("ADMIN")).findFirst();

**min / max** — extreme by comparator:

Optional<User> oldest = users.stream().max(Comparator.comparingInt(User::getAge));

**reduce** — combine all elements into one result:

int totalAge = users.stream().mapToInt(User::getAge).sum();
String concat = words.stream().reduce("", (a, b) -> a + b);

For numbers, prefer mapToInt/mapToLong/mapToDouble followed by sum() or average() — they avoid autoboxing.

**forEach(Consumer)** — perform an action on each element. Use sparingly; if you're just doing side effects, a plain loop is often clearer.

Real-world patterns

**Group and count.** "How many orders per status?"

Map<Status, Long> counts = orders.stream()
    .collect(Collectors.groupingBy(Order::getStatus, Collectors.counting()));

**Aggregate within groups.** "Total revenue per region."

Map<String, BigDecimal> revenueByRegion = orders.stream()
    .collect(Collectors.groupingBy(
        Order::getRegion,
        Collectors.reducing(BigDecimal.ZERO, Order::getAmount, BigDecimal::add)
    ));

**Top N.** "The five oldest users."

List<User> oldest = users.stream()
    .sorted(Comparator.comparingInt(User::getAge).reversed())
    .limit(5)
    .toList();

**Index pairs with IntStream.range.** "Pair each item with its index."

IntStream.range(0, names.size())
    .mapToObj(i -> i + ": " + names.get(i))
    .forEach(System.out::println);

**Read lines from a file.**

try (Stream<String> lines = Files.lines(Path.of("data.txt"))) {
    long count = lines.filter(l -> !l.isBlank()).count();
}

Note the try-with-resources — file streams need closing.

**Filter then aggregate.** "Total revenue from active customers."

BigDecimal total = orders.stream()
    .filter(o -> o.getCustomer().isActive())
    .map(Order::getAmount)
    .reduce(BigDecimal.ZERO, BigDecimal::add);

Parallel streams — and why you usually shouldn't

Adding .parallel() makes the stream process elements in parallel across multiple threads:

long count = users.parallelStream().filter(User::isActive).count();

The JVM splits the work across threads in the common ForkJoinPool. For CPU-heavy operations on large collections, this can be a significant speedup.

**Why you usually shouldn't:**

• **Most stream pipelines are I/O-bound or simple**, not CPU-bound. Parallelism adds overhead without gains.
• **Order is no longer guaranteed** in some operations. findFirst becomes findAny-like in practice.
• **The common ForkJoinPool is shared.** All parallel streams in the JVM compete for the same threads. One badly-behaved stream affects everything.
• **Side effects become race conditions.** If your lambdas mutate shared state, parallel streams will corrupt it.
• **Stateful operations like sorted and distinct work, but lose their efficiency in parallel mode.**

**When parallel streams genuinely help:**
- The collection is large (thousands+ elements).
- The per-element work is CPU-heavy (parsing, encoding, calculations).
- The operations are stateless and order-independent.
- You've profiled and confirmed sequential streams are the bottleneck.

For most application code, leave .parallel() off. If you need real parallelism, prefer CompletableFuture for concurrent I/O or explicit ExecutorService for controlled CPU parallelism.

When NOT to use streams

Streams are a tool, not a religion. They make some code clearer, other code worse.

**Plain loops are often clearer for simple cases.**

// Stream
int max = values.stream().mapToInt(Integer::intValue).max().orElse(0);

// Loop — arguably clearer
int max = 0;
for (int v : values) {
    if (v > max) max = v;
}

For one-step operations on a list, the loop is fine. Streams shine for multi-step pipelines.

**Performance-critical hot loops.** Streams have overhead — pipeline construction, lambda dispatch, possibly boxing. For tight numeric loops, a plain for is faster. Profile if it matters.

**Side-effect-heavy logic.** Streams are designed for transformation pipelines. If your loop body does I/O, logging, updating multiple counters, or other side effects, a plain loop is more honest.

**Multi-collection coordination.** When you need to iterate two collections together, or use the index, plain for-loops or IntStream.range are often more readable than complex stream compositions.

**Debuggability.** Stack traces from streams point at the synthesised pipeline methods, not your business logic. For deeply complex pipelines, this can hurt debugging. Use .peek() or extract sub-pipelines into named methods if it matters.

The rule of thumb: streams are great when you have a clear "from X transform to Y" shape. They get worse the more side effects or interactions creep in. Trust your instinct — if the stream version is harder to read out loud, write the loop.