Stop Throwing Exceptions for Control Flow: A Simpler Approach to Error Handling in Java

Introducing a lightweight, focused library that brings the power of Result types to your Java projects without the heavy baggage.

Let’s be honest. We’ve all written — and tried to debug — Java methods that look something like this:

public UserProfile loadUserProfile(String userId) {
    if (userId == null || userId.isBlank()) {
        throw new IllegalArgumentException("User ID cannot be null or empty.");
    }

    try {
        // Network call
        String userDataJson = apiClient.fetchUser(userId);
        if (userDataJson == null) {
            // User not found is an expected outcome, not an exception
            return null; 
        }

        // Parsing
        return objectMapper.readValue(userDataJson, UserProfile.class);

    } catch (IOException e) {
        // Network or parsing failure
        log.error("Failed to process user profile for ID: " + userId, e);
        throw new RuntimeException("Could not retrieve user profile.", e);
    } catch (JsonProcessingException e) {
        log.error("Failed to parse JSON for user ID: " + userId, e);
        throw new RuntimeException("Invalid user data format.", e);
    }
}

This code is a minefield. It uses exceptions for validation (IllegalArgumentException), returns null for an expected "not found" case, and then wraps other checked exceptions in a generic RuntimeException. The method signature UserProfile loadUserProfile(String userId) lies; it doesn't just return a UserProfile. It can explode in several different ways.

What if our method signatures could be honest? What if they could explicitly state: “I will either give you a UserProfile or tell you exactly what went wrong."

This is the core idea behind explicit error handling, and it’s what the lightweight library **FP-Core-Utilities** brings to Java in a simple, focused package.

## The Paradigm Shift: From Throwing to Returning

The problem with using exceptions for control flow (like validation or “not found” scenarios) is that they are a hidden side effect. You can’t tell from the method signature that it might fail.

The functional approach is to make this possibility explicit by wrapping the return type in a container that represents both success and failure. This is where Result<T> comes in.

Result<T> is a container that holds one of two things:

• An Ok value of type T (the operation succeeded).
• A Failure object containing details about the error (the operation failed).

## Introducing FP-Core-Utilities

**FP-Core-Utilities** is a minimal, lightweight library that provides three fundamental functional constructs:

• Result<T>: For explicit, type-safe error handling.
• Failure: A structured, consistent way to represent errors.
• Pair<A, B>: A simple, immutable tuple to return two values at once.

It’s designed for developers who want the robustness of Result types without pulling in a large, comprehensive functional programming library.

Let’s refactor our original example using Result:

Java

import io.github.veerakumarak.fp.Result;
import io.github.veerakumarak.fp.Failure;

public Result<UserProfile> loadUserProfile(String userId) {
    if (userId == null || userId.isBlank()) {
        return Result.failure(Failure.with("User ID cannot be null or empty."));
    }

    // Result.of() automatically catches and wraps exceptions
    return Result.of(() -> apiClient.fetchUser(userId))
            .flatMap(userDataJson -> {
                if (userDataJson == null) {
                    return Result.failure(Failure.with("User not found."));
                }
                return Result.of(() -> objectMapper.readValue(userDataJson, UserProfile.class));
            });
}h

Look at that! The method signature Result<UserProfile> is now honest. It tells every caller that this operation might not succeed. The code is declarative, clean, and there are no hidden try-catch blocks or null return values to worry about.

## The Power of Chaining with map and flatMap

The real elegance of this pattern comes from chaining operations. Result provides a fluent API to transform the successful value without ever having to write an if (result.isOk()) check.

• map(Function<T, U> fn): If the result is Ok, it applies a function to the contained value. If it's a Failure, it does nothing.
• flatMap(Function<T, Result<U>> fn): Use this when you want to chain multiple operations that also return a Result.

Imagine you need to fetch a user, and if successful, get their email and find its length.

Java

public Result<String> getUserEmail(int userId) {
    // Returns Result.ok("user@example.com") or a failure
}

Result<Integer> emailLengthResult = getUserEmail(123)
        .map(email -> email.toUpperCase()) // map: transforms the successful String
        .map(upperEmail -> upperEmail.length()); // map: transforms the String to an Integer

emailLengthResult.ifOk(length -> {
    System.out.println("Email length is: " + length);
});

emailLengthResult.ifFailure(failure -> {
    System.err.println("Could not get email length: " + failure.getMessage());
});

If getUserEmail had failed, the map calls would have been skipped automatically. The final emailLengthResult would just hold the original failure. This is often called "railway oriented programming"—the code stays on the "success track" until a failure occurs, at which point it switches to the "failure track" and bypasses all subsequent steps.

## Why Not Just Use a Bigger Library like Vavr?

This library’s Result type is inspired by the explicit error handling patterns found in Rust's Result<T, E>, Vavr's Try and Either, and the clear error returns common in Go's (value, error) style.

Vavr is a fantastic and comprehensive functional library for Java. It includes immutable collections, advanced pattern matching, Option, Either, Try, and so much more. It’s a full toolbox.

FP-Core-Utilities is a scalpel. It’s for when you want to solve the specific, painful problem of error handling with a lightweight, zero-fuss dependency. To maintain this minimalist philosophy, it intentionally leverages Java’s built-in java.util.Optional for null-safety instead of adding a custom Option type. It’s the perfect way to introduce the benefits of Result types to your team or project without the learning curve or dependency weight of a larger library.

## Get Started

Adding explicit error handling to your code makes it more robust, predictable, and a pleasure to read. You force consumers of your API to acknowledge and handle failure paths, leading to fewer bugs.

Give FP-Core-Utilities a try. You can add it to your project with a simple Maven or Gradle dependency.

Maven

<dependency>
    <groupId>io.github.veerakumarak</groupId>
    <artifactId>fp</artifactId>
    <version>5.1.0</version>
</dependency>

Gradle

implementation 'io.github.veerakumarak:fp:4.0.0'

Start with one messy module, refactor it to use Result, and see how much cleaner it becomes. Your future self will thank you.

## Source Code and Contributing

This library is open-source, and the code is available on GitHub. Contributions are welcome! If you have suggestions for improvements, new features, or bug fixes, please feel free to open an issue or submit a pull request.

• GitHub Repository: https://github.com/veerakumarak/fp