Java Stream findFirst() Method with Examples

3 min readSep 27, 2024

The findFirst() method in Java is a part of the java.util.stream.Stream interface. In this guide, we will learn how to use findFirst() method in Java with practical examples and real-world use cases to better understand its usage.

Learn Java from scratch: Learn Java Programming.

Complete Java Reference: Java API Documentation.

Introduction
findFirst() Method Syntax
Understanding findFirst()
Examples
Real-World Use Case
Conclusion

Introduction

The Stream.findFirst() method in Java returns an Optional containing the first element of the stream. It’s useful when you want to get the first matching element.

This method is typically used with ordered streams where the first element is important.

findFirst() is often used when you need the first result after filtering or processing a stream.

findFirst() Method Syntax

The syntax for the findFirst() method is as follows:

Optional<T> findFirst()

Parameters:

This method does not take any parameters.

Returns:

An Optional<T> describing the first element of the stream, or an empty Optional if the stream is empty.

Throws:

This method does not throw any exceptions.

Understanding findFirst()

The findFirst() method allows you to retrieve the first element from the stream. This is particularly useful for ordered streams where the order of elements is significant. In parallel streams, findFirst() may be more costly compared to findAny() because it requires maintaining order.

Examples

Basic Usage

To demonstrate the basic usage of findFirst(), we will create a Stream and use findFirst() to retrieve the first element from the stream.

import java.util.Optional;
import java.util.stream.Stream;

public class FindFirstExample {
    public static void main(String[] args) {
        Stream<String> stream = Stream.of("apple", "banana", "cherry");

        // Use findFirst() to retrieve the first element from the stream
        Optional<String> firstElement = stream.findFirst();

        // Print the element if present
        firstElement.ifPresent(System.out::println);
    }
}

Output:

apple

Using `findFirst()` with Filtered Streams

This example shows how to use findFirst() in combination with filtering to retrieve the first element that matches a specific condition.

import java.util.Optional;
import java.util.stream.Stream;

public class FindFirstWithFilterExample {
    public static void main(String[] args) {
        Stream<String> stream = Stream.of("apple", "banana", "cherry", "date", "elderberry");

        // Filter elements that start with 'c' and use findFirst() to retrieve the first matching element
        Optional<String> firstElement = stream.filter(s -> s.startsWith("c")).findFirst();

        // Print the element if present
        firstElement.ifPresent(System.out::println);
    }
}

Output:

cherry

Real-World Use Case: Finding the First High-Priority Task

In real-world applications, the findFirst() method can be used to find the first high-priority task from a stream of tasks, ensuring that the first matching task is retrieved and processed.

import java.util.Optional;
import java.util.stream.Stream;

public class FindFirstHighPriorityTaskExample {
    static class Task {
        String description;
        boolean highPriority;

        Task(String description, boolean highPriority) {
            this.description = description;
            this.highPriority = highPriority;
        }

        boolean isHighPriority() {
            return highPriority;
        }

        @Override
        public String toString() {
            return description;
        }
    }

    public static void main(String[] args) {
        Stream<Task> tasks = Stream.of(
            new Task("Task 1", false),
            new Task("Task 2", true),
            new Task("Task 3", true)
        );

        // Use findFirst() to find the first high-priority task
        Optional<Task> firstHighPriorityTask = tasks.filter(Task::isHighPriority).findFirst();

        // Print the high-priority task if present
        firstHighPriorityTask.ifPresent(task -> System.out.println("First high-priority task: " + task));
    }
}

Output:

First high-priority task: Task 2

Conclusion

The Stream.findFirst() method is used to return an Optional describing the first element of the stream, or an empty Optional if the stream is empty. This method is particularly useful for ordered streams where the order of elements matters.

By understanding and using this method, you can efficiently manage and process streams of values in your Java applications, ensuring that the first matching element is retrieved when needed.

Original Post: