Why functional programming in Java?

Functional programming in Java is not about recreating Haskell inside the JVM. It is about a smaller claim: code is easier to reason about when data flows explicitly through transformations instead of hiding in mutable fields and thrown exceptions. This series builds jfp, a small dependency-free library that makes that claim concrete — Option, Result, Validated, Lazy, and a handful of algebraic types — while comparing every abstraction with what the JDK already gives you.

The running example is a government scheme engine: a service that decides whether a citizen is eligible for a benefit, given registry lookups, income limits, and evidence documents. It is a good fit because its requirements — auditability, explainable decisions, expected failure modes — are exactly the places where hidden state and invisible control flow hurt most.

The problem in one handler

This is the shape of the code the series is replacing. Anyone who has written a service in anger has written it:

1
public EligibilityOutcome evaluate(EligibilityRequest request) {
2
    CitizenFacts facts = citizenRegistry.find(request.citizenId()); // null? throws?
3
    if (facts == null) {
4
        return new Ineligible(request.schemeCode(), request.citizenId(),
5
                List.of("citizen not found"));
6
    }
7
    LandRecord land;
8
    try {
9
        land = landRegistry.fetch(request.citizenId()); // timeout -> exception
10
    } catch (RegistryTimeoutException e) {
11
        return new ManualReview(request.schemeCode(), request.citizenId(), "registry timeout");
12
    }
13
    boolean eligible = facts.resident()
14
            && facts.annualHouseholdIncome() <= INCOME_LIMIT
15
            && land.areaHectares() > 0;
16
    // ... and somewhere else, a mutable audit buffer is appended to
17
    return eligible ? new Eligible(...) : new Ineligible(...);
18
}

Three problems hide here. Absence is null, failure is an exception, and both look identical to the compiler. The decision logic is entangled with I/O, so you cannot test the policy without mocking the world. And the audit trail — the thing a government system actually needs — is a side effect that happens “somewhere else.” By the end of the series each of those has an explicit, typed replacement.

What you will build

The artifact is a Java 21 library organized by what each piece does:

1
jfp/
2
├── core/      Fn1, Functions, Tuple2, Lazy
3
├── data/      Option, Result, Either, Validated, NonEmptyList
4
├── algebra/   Semigroup, Monoid, Foldable
5
├── effect/    IO, Reader, State
6
└── interop/   Optionals, Streams, Futures

You need JDK 21 and Gradle 8.x. Everything in the series is plain Java — no annotation processors, no bytecode tricks, no dependencies beyond JUnit and AssertJ for tests.

Project setup

1
rootProject.name = "jfp"

1
plugins {
2
    `java-library`
3
}
4

5
group = "in.o612.eng.jfp"
6
version = "0.1.0-SNAPSHOT"
7

8
java {
9
    toolchain {
10
        languageVersion.set(JavaLanguageVersion.of(21))
11
    }
12
}
13

14
repositories {
15
    mavenCentral()
16
}
17

18
dependencies {
19
    testImplementation(platform("org.junit:junit-bom:5.11.0"))
20
    testImplementation("org.junit.jupiter:junit-jupiter")
21
    testImplementation("org.assertj:assertj-core:3.26.3")
22
}
23

24
tasks.test {
25
    useJUnitPlatform()
26
}

The java-library plugin matters later if you publish: it separates api from implementation dependencies, so consumers of jfp do not inherit your test stack. gradle build on an empty project should succeed in a few seconds — that is your milestone check for this chapter.

The first type: a function worth naming

Java already has Function<T, R>. We define our own unary function anyway, for two reasons: it gives the library a consistent vocabulary (apply, andThen, compose), and later chapters hang methods on it that Function does not carry. For now it is deliberately minimal:

1
package in.o612.eng.jfp.core;
2

3
@FunctionalInterface
4
public interface Fn1<T, R> {
5
    R apply(T value);
6
}

And the domain value the pipeline will transform — a Java 21 record, immutable by construction:

1
package in.o612.eng.jfp.scheme;
2

3
public record EligibilityRequest(
4
        String citizenId,
5
        String schemeCode
6
) {}

That is the whole foundation. The next chapter turns Fn1 into something composable — and states the two laws that make composition safe to refactor.