Java Streams: Complete Guide to Filtering, Mapping, and Collecting

Introduction to Java Streams

Before Java 8, processing a collection meant writing loops, managing temporary variables, and dealing with bulky boilerplate code. If you wanted to find all students with a grade over 90, sort them by name, and put them in a new list, you had to write several lines of imperative code.

The Stream API , introduced in Java 8, changed this by allowing you to process collections in a declarative way. Instead of specifying *how* to iterate (the loop), you specify *what* you want to achieve (filter, sort, collect). A Stream is not a data structure that stores elements; it is a pipeline that carries computations from a source (like an ArrayList or a HashMap ) to a result.

Prerequisites

To get the most out of this tutorial, you should be comfortable with:

• Using basic collections like ArrayList and the for-each loop
• Writing Lambda expressions and understanding functional interfaces
• Basic knowledge of Generics (e.g., List<String> )

What You Will Learn

• How to create a Stream from a collection
• The difference between intermediate and terminal operations
• How to use filter , map , sorted , and distinct
• How to convert a Stream back into a List or Map using Collectors
• How to reduce a stream to a single value
• Common pitfalls, such as modifying a collection while streaming

How Streams Work: Pipelines

A Stream pipeline consists of three parts:

1. Source: Where the data comes from (e.g., a List, an Array, or I/O channels).
2. Intermediate Operations: Operations that transform the stream (e.g., filtering, mapping). They are lazy , meaning they don't actually execute until a terminal operation is called. They return a new stream.
3. Terminal Operation: An operation that produces a result (like a List, an integer, or printing to the console) or a side-effect. This triggers the actual processing of the data. Once called, the stream is consumed.

List<String> names = List.of("Alice", "Bob", "Charlie");

List<String> result = names.stream()       // 1. Source
    .filter(name -> name.length() > 3)    // 2. Intermediate (lazy)
    .map(String::toUpperCase)         // 2. Intermediate (lazy)
    .collect(Collectors.toList());   // 3. Terminal (executes pipeline)

Common Stream Operations Syntax

// filter(Predicate) - Keeps elements that match the condition
.filter(e -> e.isActive())

// map(Function) - Transforms each element into another type
.map(e -> e.getName())

// sorted() - Sorts naturally (must implement Comparable)
.sorted()

// sorted(Comparator) - Sorts using a custom rule
.sorted(Comparator.comparing(Person::getAge))

// distinct() - Removes duplicates
.distinct()

// limit(long) - Takes only the first N elements
.limit(5)

// forEach(Consumer) - Performs an action on each element (Terminal)
.forEach(System.out::println)

// count() - Returns the number of elements (Terminal)
.count()

// collect(Collector) - Converts stream to a Collection/Map (Terminal)
.collect(Collectors.toList())

Simple Example: Filtering and Mapping

Let's take a list of numbers, filter out the even ones, double the remaining values, and collect them into a new list.

import java.util.List;
import java.util.stream.Collectors;

public class StreamBasics {
    public static void main(String[] args) {
        List<Integer> numbers = List.of(1, 2, 3, 4, 5, 6);

        List<Integer> processedNumbers = numbers.stream()
            .filter(n -> n % 2 != 0)     // Keep only odd numbers: 1, 3, 5
            .map(n -> n * 2)                // Double them: 2, 6, 10
            .collect(Collectors.toList()); // Collect to a List

        System.out.println(processedNumbers);
    }
}

How It Works: Lazy Evaluation

In the example above, no elements are actually processed until .collect() is called. When .collect() is invoked, Java looks back up the pipeline and figures out the most efficient way to process the data.

For instance, if you filter 1,000,000 elements down to 5, and then map those 5, Java will only execute the mapping function 5 times. It will not map all 1,000,000 elements and throw away the results. This lazy evaluation is what makes Streams highly efficient for large datasets.

Real-World Example: Processing Transactions

Imagine you have a list of bank transactions. You need to find all transactions over $500 made in the "Groceries" category, sort them by amount (highest first), and extract just the transaction IDs.

import java.util.List;
import java.util.stream.Collectors;

class Transaction {
    private String id;
    private String category;
    private double amount;

    public Transaction(String id, String category, double amount) {
        this.id = id;
        this.category = category;
        this.amount = amount;
    }

    public String getId() { return id; }
    public String getCategory() { return category; }
    public double getAmount() { return amount; }
}

public class TransactionProcessor {
    public static void main(String[] args) {
        List<Transaction> transactions = List.of(
            new Transaction("T001", "Groceries", 150.50),
            new Transaction("T002", "Utilities", 600.00),
            new Transaction("T003", "Groceries", 550.25),
            new Transaction("T004", "Groceries", 50.00)
        );

        List<String> highValueGroceryIds = transactions.stream()
            .filter(t -> t.getCategory().equals("Groceries"))
            .filter(t -> t.getAmount() > 500)
            .sorted((t1, t2) -> Double.compare(t2.getAmount(), t1.getAmount()))
            .map(Transaction::getId)
            .collect(Collectors.toList());

        System.out.println("High-value grocery transaction IDs: " + highValueGroceryIds);
    }
}

This demonstrates the true power of Streams. The code reads exactly like the business requirement: filter by category, filter by amount, sort descending, extract IDs, collect.

Collecting Results: The Collectors Class

The Collectors class provides many utility methods for converting stream results into different data structures.

import java.util.*;
import java.util.stream.Collectors;

public class CollectorsExamples {
    public static void main(String[] args) {
        List<String> names = List.of("Alice", "Bob", "Alice", "Charlie");

        // 1. Collect to a List
        List<String> nameList = names.stream().collect(Collectors.toList());

        // 2. Collect to a Set (automatically removes duplicates)
        Set<String> uniqueNames = names.stream().collect(Collectors.toSet());

        // 3. Join strings into a single String
        String joined = names.stream().collect(Collectors.joining(", "));
        System.out.println("Joined: " + joined);

        // 4. Grouping by a property (returns Map<K, List<V>>)
        Map<Integer, List<String>> byLength = names.stream()
            .collect(Collectors.groupingBy(String::length));
        System.out.println("Grouped by length: " + byLength);

        // 5. Summing values
        int totalLength = names.stream().collect(Collectors.summingInt(String::length));
        System.out.println("Total characters: " + totalLength);
    }
}

Common Mistakes to Avoid

Mistake 1: Modifying the Source Collection During Streaming

Just like with a standard for-each loop, modifying the underlying collection (adding or removing elements) while a stream is processing it will throw a ConcurrentModificationException .

List<String> list = new ArrayList<>(List.of("A", "B"));

// Throws ConcurrentModificationException
list.stream().filter(s -> !s.equals("B"))
     .forEach(s -> list.remove(s)); 

// Collect the results into a new list first, then modify the original
List<String> toRemove = list.stream()
     .filter(s -> !s.equals("B"))
     .collect(Collectors.toList());

list.removeAll(toRemove); // Safe modification

Mistake 2: Reusing a Stream

Streams are designed to be consumed exactly once. If you store a stream in a variable and call a terminal operation on it twice, the second call will throw an IllegalStateException .

Mistake 3: Using Streams Only for Side Effects

Using .forEach() to modify external state (like adding elements to an external list) is considered bad practice because it breaks the declarative nature of streams. If your goal is to produce a result, use .collect() instead.

Best Practices

1. Keep Pipelines Short: If a stream pipeline gets too long (e.g., more than 5-6 operations), break it up into intermediate variables with descriptive names to improve readability.
2. Use Method References: Replace simple lambdas like s -> s.toUpperCase() with method references like String::toUpperCase for cleaner code.
3. Avoid Complex Lambdas: If a lambda in a map or filter requires multiple lines or complex logic, extract it into a separate, well-named private method.
4. Use Primitive Streams for Primitives: When working with int , double , or long , use .mapToInt() , .mapToDouble() , etc. This avoids the performance overhead of boxing primitives into objects (e.g., converting int to Integer ).

Performance Considerations

• Overhead: Streams have slight setup overhead compared to standard for-loops. For very simple operations on tiny lists, a for-loop is technically faster. However, for complex data processing, the JVM heavily optimizes streams, and the performance difference becomes negligible.
• Parallel Streams: You can call .parallelStream() to split the work across multiple CPU cores. However, parallel streams have significant overhead (thread pooling, splitting, merging results) and should only be used for large datasets with computationally heavy operations. Using parallelStream() on a list of 100 items will actually be slower than a standard stream.
• Stateful Operations: Avoid operations like sorted() or distinct() on parallel streams. They require the entire dataset to be analyzed and merged, which destroys the benefit of parallel processing.

Related Concepts

• Lambda Expressions — The syntax used to pass behavior into stream operations.
• ArrayList — The most common source from which Streams are created.
• HashMap — How to stream over keys, values, or entries of a Map.
• Methods — Understanding how methods work is crucial for writing clean stream pipelines.

Exercises

Solutions

import java.util.List;
import java.util.stream.Collectors;

public class StreamExercise1 {
    public static void main(String[] args) {
        List<String> fruits = List.of("apple", "BANANA", "Cherry", "date");

        String result = fruits.stream()
            .map(String::toUpperCase)         // [APPLE, BANANA, CHERRY, DATE]
            .filter(s -> !s.startsWith("B"))  // [APPLE, CHERRY, DATE]
            .collect(Collectors.joining("-")); // APPLE-CHERRY-DATE

        System.out.println(result);
    }
}

import java.util.List;
import java.util.Optional;

public class StreamExercise2 {
    public static void main(String[] args) {
        List<Integer> numbers = List.of(12, 45, 7, 89, 32, 4);

        // max() returns an Optional<Integer> because the list might be empty
        Optional<Integer> max = numbers.stream().max(Integer::compare);

        // Safely handle the Optional
        if (max.isPresent()) {
            System.out.println("The highest number is: " + max.get());
        } else {
            System.out.println("The list is empty.");
        }
        
        // Or using the modern Optional API (preferred)
        max.ifPresent(val -> System.out.println("Highest: " + val));
    }
}

Summary

• Streams provide a declarative way to process collections, focusing on what to do rather than how to do it.
• A pipeline consists of a Source, Intermediate operations (lazy), and a Terminal operation (eager).
• Common intermediate operations include filter , map , sorted , and distinct .
• Common terminal operations include collect , forEach , count , and reduce .
• Use the Collectors class to convert streams back into Lists, Sets, Maps, or Strings.
• Never modify the underlying collection while streaming, and never reuse a consumed stream.

Frequently Asked Questions

Continue Learning