143-java-functional-exception-handling
npx machina-cli add skill jabrena/cursor-rules-java/143-java-functional-exception-handling --openclawJava Functional Exception handling Best Practices
Identify and apply functional exception handling best practices in Java to improve error clarity, maintainability, and performance by eliminating exception overuse in favour of monadic error types.
Core areas: Optional<T> for nullable values over throwing NullPointerException or NotFoundException, VAVR Either<L,R> for predictable business-logic failures, CompletableFuture<T> for async error handling, sealed classes and records for rich error type hierarchies with exhaustive pattern matching, enum-based error types for simple failure cases, functional composition with flatMap/map/peek/peekLeft for chaining operations that can fail, structured logging at appropriate severity levels (warn/info for business failures, error for system failures), checked vs unchecked exception discipline, and exception chaining with full causal context when exceptions are unavoidable.
Prerequisites: Run ./mvnw validate before applying any changes. If validation fails, stop immediately — do not proceed until the project is in a valid state. Also confirm the VAVR dependency (io.vavr:vavr) and SLF4J are present when introducing Either types.
Multi-step scope: Step 1 validates the project compiles. Step 2 categorizes error handling opportunities by impact (CRITICAL, MAINTAINABILITY, PERFORMANCE, EXPRESSIVENESS) and area (exception overuse, monadic gaps, error type design, functional composition). Step 3 replaces exceptions for nullable/not-found cases with Optional. Step 4 replaces multiple checked exceptions for business logic with VAVR Either<L,R> types. Step 5 designs comprehensive error types — enums for simple cases, sealed classes/records for complex hierarchies. Step 6 implements monadic composition pipelines (flatMap/map) to replace imperative try-catch control flow. Step 7 aligns logging to functional patterns (warn/info for functional errors, error only for system failures). Step 8 reserves RuntimeException subclasses only for programming errors and truly exceptional system failures. Step 9 adds JavaDoc documenting Either return types and their left/right values. Step 10 runs ./mvnw clean verify to confirm all tests pass after changes.
Before applying changes: Read the reference for detailed good/bad examples, constraints, and safeguards for each functional exception handling pattern.
Reference
For detailed guidance, examples, and constraints, see references/143-java-functional-exception-handling.md.
Source
git clone https://github.com/jabrena/cursor-rules-java/blob/main/skills/143-java-functional-exception-handling/SKILL.mdView on GitHub Overview
This skill guides applying functional exception handling in Java to improve error clarity, maintainability, and performance. It emphasizes replacing exception overuse with Optional and VAVR Either, building rich error hierarchies with sealed types and enums, and using monadic pipelines and functional control flow, reserving exceptions for truly exceptional system failures.
How This Skill Works
Code uses Optional<T> to model nullable or not-found results, and VAVR Either<L,R> to represent predictable business-logic failures. Monadic composition with map/flatMap/peek/peekLeft wires together steps, while sealed classes/records or enums define exhaustive error types. CompletableFuture<T> enables async error handling, and logging follows functional patterns (warn/info for business errors, error for system faults) with proper causality chaining.
When to Use It
- When you want to reduce exception proliferation by modeling absence or not-found cases with Optional or Either.
- When business-logic failures should be propagated without throwing checked exceptions.
- When you need to compose multiple operations in a single, readable functional pipeline.
- When you want a structured error type system using sealed classes/records and enums.
- When validating and maintaining error handling patterns to improve maintainability and performance.
Quick Start
- Step 1: Run ./mvnw validate to ensure project health and confirm VAVR/SLF4J presence.
- Step 2: Identify nullable/not-found paths and business-rule failures; replace with Optional and Either.
- Step 3: Implement monadic pipelines (map/flatMap) and align logging; run ./mvnw clean verify.
Best Practices
- Prefer Optional<T> for nullable/not-found results over throwing NotFoundException or NPE.
- Use Vavr Either<L,R> to represent predictable business failures; left holds error info, right holds success.
- Adopt CompletableFuture<T> for async error handling to keep error flow reactive and composable.
- Design error types with sealed classes/records (and enums for simple cases) for exhaustive pattern matching.
- Compose error handling with map/flatMap/peek/peekLeft, and log with warn/info for business issues and error for system failures.
Example Use Cases
- Repository.findUserById(id) returns Optional<User> instead of throwing when not found.
- Service layer methods return Either<BusinessError, UserProfile> to propagate domain failures.
- Async service calls return CompletableFuture<Either<AsyncError, Result>> to model async errors without exceptions.
- Error type hierarchy uses sealed classes like UserError and subtypes for specific conditions.
- Logging distinguishes functional errors (warn/info) from system faults (error) with contextual messages and causes.
