# Introduction
A Java library to handle success and failure without exceptions
## Handle success and failure in Java without exceptions
Wave goodbye to slow exceptions and embrace clean, efficient error handling by encapsulating operations that may succeed or fail in a type-safe way.
Start hereFork me on GitHub
{% hint style="success" %}
Result is a Java library for modeling operation outcomes explicitly. It gives you a simpler, faster alternative to exception-driven flow when you want to represent both success and failure in a single, composable type.
{% endhint %}
### Why Result?
Optional is great for values that may be present or absent, but it does not explain **why** something is missing. Result fills that gap by carrying either a successful value or a failure reason, so your code can describe what happened instead of hiding it.
### Quick Start
{% stepper %}
{% step %}
**Create a result from an operation**
```java
Result result = Results.ofCallable(() -> db.getUser(id));
```
{% endstep %}
{% step %}
**Inspect whether it succeeded or failed**
```java
result.ifFailure(error -> logger.error("Couldn't get user: {}", id, error));
```
{% endstep %}
{% step %}
**Transform it if needed, then unwrap it as required**
```java
String name = result.mapSuccess(User::name).orElse("Anonymous");
```
{% endstep %}
{% endstepper %}
### Latest Releases
Available in [](https://central.sonatype.com/artifact/com.leakyabstractions/result/)
### Ready to Tap into the Power of Results?
Read the guide and transform your error handling today.
{% content-ref url="/pages/4mPpfvbb7pgfQaPrChmN" %}
[Getting Started](/docs/start)
{% endcontent-ref %}
{% content-ref url="/pages/NF0v4IGYyNzpoWOFrbeh" %}
[Basic Usage](/docs/basic)
{% endcontent-ref %}
{% content-ref url="/pages/9e1kunsGc7QFZHqrzzLE" %}
[Advanced Usage](/docs/advanced)
{% endcontent-ref %}
Also available as an **ebook** in multiple formats. [Download your free copy now!](https://leanpub.com/result/)
### TL;DR
Not a fan of reading long docs? No worries! Tune in to *Deep Dive*, a podcast generated by [NetbookLM](https://notebooklm.google.com/). In just a few minutes, you'll get the essential details and a fun intro to what this library can do for you!
{% embed url="" %}
# Getting Started
How to get up and running with Results in no time
{% hint style="success" %}
The best way to think of Results is as a super-powered version of Java's Optionals.
{% endhint %}
`Result` builds upon the familiar concept of `Optional`, enhancing it with the ability to represent both success and failure states.
{% tabs %}
{% tab title="Why Results over Optionals?" %}
`Optional` class is useful for representing values that might be present or absent, eliminating the need for null checks. However, Optionals fall short when it comes to error handling because they do not convey why a value is lacking. `Result` addresses this limitation by encapsulating both successful values and failure reasons, offering a more expressive way to reason about what went wrong.
{% endtab %}
{% tab title="Result API" %}
Results provide the same methods as Optionals, plus additional ones to handle failure states effectively.
| [`Optional`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html) | [`Result`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html) |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [isPresent](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#isPresent\(\)) | [hasSuccess](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#hasSuccess--) |
| [isEmpty](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#isEmpty\(\)) | [hasFailure](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#hasFailure--) |
| [get](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#get\(\)) | [getSuccess](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#getSuccess--) |
| | [getFailure](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#getFailure--) |
| [orElse](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#orElse\(java.lang.Object\)) | [orElse](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#orElse-S-) |
| [orElseGet](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#orElseGet\(java.util.function.Supplier\)) | [orElseMap](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#orElseMap-java.util.function.Function-) |
| [stream](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#stream\(\)) | [streamSuccess](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#streamSuccess--) |
| | [streamFailure](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#streamFailure--) |
| [ifPresent](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#ifPresent\(java.util.function.Consumer\)) | [ifSuccess](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#ifSuccess-java.util.function.Consumer-) |
| | [ifFailure](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#ifFailure-java.util.function.Consumer-) |
| [ifPresentOrElse](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#ifPresentOrElse\(java.util.function.Consumer,java.lang.Runnable\)) | [ifSuccessOrElse](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#ifSuccessOrElse-java.util.function.Consumer-java.util.function.Consumer-) |
| [filter](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#filter\(java.util.function.Predicate\)) | [filter](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#filter-java.util.function.Predicate-java.util.function.Function-) |
| | [recover](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#recover-java.util.function.Predicate-java.util.function.Function-) |
| [map](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#map\(java.util.function.Function\)) | [mapSuccess](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#mapSuccess-java.util.function.Function-) |
| | [mapFailure](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#mapFailure-java.util.function.Function-) |
| | [map](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#map-java.util.function.Function-java.util.function.Function-) |
| [flatMap](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#flatMap\(java.util.function.Function\)) | [flatMapSuccess](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#flatMapSuccess-java.util.function.Function-) |
| [or](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#or\(java.util.function.Supplier\)) | [flatMapFailure](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#flatMapFailure-java.util.function.Function-) |
| | [flatMap](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#flatMap-java.util.function.Function-java.util.function.Function-) |
| {% endtab %} | |
| {% endtabs %} | |
By leveraging Results, you can unleash a powerful tool for error handling that goes beyond the capabilities of traditional Optionals, leading to more robust and maintainable Java code.
## Results in a Nutshell
In Java, methods that can fail typically do so by throwing exceptions. Then, exception-throwing methods are called from inside a `try` block to handle errors in a separate `catch` block.
This approach is lengthy, and that's not the only problem — it's also very slow.
{% hint style="info" %}
Conventional wisdom says **exceptional logic shouldn't be used for normal program flow**. Results make us deal with expected error situations explicitly to enforce good practices and make our programs [run faster](/extra/benchmarks).
{% endhint %}
Let's now look at how the above code could be refactored if `connect()` returned a `Result` object instead of throwing an exception.
In the example above, we used only 4 lines of code to replace the 10 that worked for the first one. But we can effortlessly make it shorter by chaining methods. In fact, since we were returning `-1` just to signal that the underlying operation failed, we are better off returning a `Result` object upstream. This will allow us to compose operations on top of `getServerUptime()` just like we did with `connect()`.
{% hint style="success" %}
`Result` objects are immutable, providing thread safety without the need for synchronization. This makes them ideal for multi-threaded applications, ensuring predictability and eliminating side effects.
{% endhint %}
# Adding Result to Your Build
How to add Result as a dependency to your build
This library adheres to [Pragmatic Versioning](https://pragver.github.io/) to communicate the backwards compatibility of each version.
The latest releases are available in [](https://central.sonatype.com/artifact/com.leakyabstractions/result/)
Result supports both [**Maven**](https://maven.apache.org/) and [**Gradle**](https://gradle.org/) for seamless integration into your Java build workflow.
Cover image
Cover image (dark)
Apache Maven is a convention-based Java build tool that uses XML configuration to manage dependencies, compile code, and package applications in a standardized lifecycle.
Gradle is a flexible and high-performance build tool that uses a Groovy or Kotlin DSL to define builds, offering advanced customization and fast incremental builds.
## Artifact Coordinates
Add this Maven dependency to your build:
| Group ID | Artifact ID | Latest Version |
| ----------------------- | ----------- | --------------------------------------------------------------------------------------------- |
| `com.leakyabstractions` | `result` |  |
{% hint style="success" %}
[Maven Central](https://central.sonatype.com/artifact/com.leakyabstractions/result/) provides snippets for different build tools to declare this dependency.
{% endhint %}
## Maven
Add Result as a Maven dependency to your project.
```xml
com.leakyabstractionsresult1.0.0.0
```
## Gradle
Add Result as a Gradle dependency to your project.
```groovy
dependencies {
implementation("com.leakyabstractions:result:1.0.0.0")
}
```
{% hint style="info" %}
This is the most common configuration for projects using Result internally. If we were building a library that exposed Result in its public API, [we should use `api` instead of `implementation`](https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_separation).
{% endhint %}
## Conclusion
We learned how to add the library to your project using either Maven or Gradle. By including the correct dependencies, you're now ready to start leveraging the power of Results in your applications.
# Creating Results
How to instantiate new Result objects
There are several ways to create result objects.
## Successful Results
A successful result contains a non-null value produced by an operation when everything works as intended. We can use [`Results::success`](https://javadoc.io/doc/com.leakyabstractions/result/latest/com/leakyabstractions/result/core/Results.html#success-S-) to create a new instance.
```java
@Test
void testSuccess() {
// When
Result result = Results.success(200);
// Then
assertTrue(result::hasSuccess);
assertFalse(result::hasFailure);
}
```
{% hint style="info" %}
Note that we can invoke [`Result::hasSuccess`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#hasSuccess--) or [`Result::hasFailure`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#hasFailure--) to check whether a result is successful or failed (more on this in the [next section](/docs/basic/checking)).
{% endhint %}
## Failed Results
On the other hand, a failed result holds a value representing the problem that prevented the operation from completing. We can use [`Results::failure`](https://javadoc.io/doc/com.leakyabstractions/result/latest/com/leakyabstractions/result/core/Results.html#failure-F-) to create a new one.
```java
@Test
void testFailure() {
// When
Result result = Results.failure("The operation failed");
// Then
assertTrue(result::hasFailure);
assertFalse(result::hasSuccess);
}
```
{% hint style="danger" %}
Failure values cannot be `null` either.
{% endhint %}
## Results Based on Nullable Values
When we need to create results that depend on a possibly null value, we can use [`Results::ofNullable`](https://javadoc.io/doc/com.leakyabstractions/result/latest/com/leakyabstractions/result/core/Results.html#ofNullable-S-F-). If the first argument is `null`, then the second one will be used to create a failed result.
```java
@Test
void testOfNullable() {
// Given
String string1 = "The operation succeeded";
String string2 = null;
// When
Result result1 = Results.ofNullable(string1, 404);
Result result2 = Results.ofNullable(string2, 404);
// Then
assertTrue(result1::hasSuccess);
assertTrue(result2::hasFailure);
}
```
{% hint style="info" %}
The second argument can be either a failure value or a function that produces a failure value.
{% endhint %}
## Results Based on Optionals
We can also use [`Results::ofOptional`](https://javadoc.io/doc/com.leakyabstractions/result/latest/com/leakyabstractions/result/core/Results.html#ofOptional-java.util.Optional-F-) to create results that depend on an [`Optional`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html) value. If the first argument is an empty optional, then the second one will be used to create a failed result.
```java
@Test
void testOfOptional() {
// Given
Optional optional1 = Optional.of(BigDecimal.ONE);
Optional optional2 = Optional.empty();
// When
Result result1 = Results.ofOptional(optional1, -1);
Result result2 = Results.ofOptional(optional2, -1);
// Then
assertTrue(result1::hasSuccess);
assertTrue(result2::hasFailure);
}
```
{% hint style="info" %}
The second argument can be a [`Supplier`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/function/Supplier.html) too.
{% endhint %}
## Results Based on Callables
Finally, if we have a task that may either return a success value or throw an exception, we can encapsulate it as a result using [`Results::ofCallable`](https://javadoc.io/doc/com.leakyabstractions/result/latest/com/leakyabstractions/result/core/Results.html#ofCallable-java.util.concurrent.Callable-) so we don't need to use a *try-catch* block.
```java
String task1() {
return "OK";
}
String task2() throws Exception {
throw new Exception("Whoops!");
}
@Test
void testOfCallable() {
// When
Result result1 = Results.ofCallable(this::task1);
Result result2 = Results.ofCallable(this::task2);
// Then
assertTrue(result1::hasSuccess);
assertTrue(result2::hasFailure);
}
```
{% hint style="success" %}
This method enables compatibility with legacy or third-party code that uses exceptions to indicate operation failure.
{% endhint %}
## Conclusion
We've covered how to create new instances of `Result` using various factory methods provided by the `Results` class. Each method serves a specific purpose, allowing you to select the most suitable one based on the situation.
# Basic Usage
How to solve simple use-case scenarios
In this section, we'll cover foundational use cases, including checking the status of a result, unwrapping the value inside a result, and taking different actions based on success or failure.
These basics will help you handle errors more cleanly and efficiently without cluttering your code with *try-catch* blocks.
# Checking Success or Failure
How to find out if the operation succeded or failed
As we discovered earlier, we can easily determine if a given `Result` instance is successful or not.
## Checking Success
We can use [`Result::hasSuccess`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#hasSuccess--) to obtain a `boolean` value that represents whether a result is successful.
```java
@Test
void testHasSuccess() {
// Given
Result result1 = success(1024);
Result result2 = failure(1024);
// When
boolean result1HasSuccess = result1.hasSuccess();
boolean result2HasSuccess = result2.hasSuccess();
// Then
assertTrue(result1HasSuccess);
assertFalse(result2HasSuccess);
}
```
## Checking Failure
We can also use [`Result::hasFailure`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#hasFailure--) to find out if a result contains a failure value.
```java
@Test
void testHasFailure() {
// Given
Result result1 = success(512);
Result result2 = failure(512);
// When
boolean result1HasFailure = result1.hasFailure();
boolean result2HasFailure = result2.hasFailure();
// Then
assertFalse(result1HasFailure);
assertTrue(result2HasFailure);
}
```
## Conclusion
We discussed how to determine the state of a Result object using [`hasSuccess`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#hasSuccess--) and [`hasFailure`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#hasFailure--). These methods provide a straightforward way to identify the outcome of an operation, helping you make decisions based on the outcome.
# Unwrapping Values
How to get values out of Result objects
In essence, a `Result` object is just a container that wraps a success or a failure value for us. Therefore, sometimes you are going to want to get that value out of the container.
{% hint style="info" %}
As useful as this may seem, we will soon realize that we won't be doing it very often.
{% endhint %}
## Unwrapping Success
The most basic way to retrieve the success value wrapped inside a result is by using [`Result::getSuccess`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#getSuccess--). This method will return an optional success value, depending on whether the result was actually successful or not.
```java
@Test
void testGetSuccess() {
// Given
Result result1 = success("SUCCESS");
Result result2 = failure("FAILURE");
// Then
Optional success1 = result1.getSuccess();
Optional success2 = result2.getSuccess();
// Then
assertEquals("SUCCESS", success1.get());
assertTrue(success2::isEmpty);
}
```
## Unwrapping Failure
Similarly, we can use [`Result::getFailure`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#getFailure--) to obtain the failure value held by a `Result` object.
```java
@Test
void testGetFailure() {
// Given
Result result1 = success("SUCCESS");
Result result2 = failure("FAILURE");
// Then
Optional failure1 = result1.getFailure();
Optional failure2 = result2.getFailure();
// Then
assertTrue(failure1::isEmpty);
assertEquals("FAILURE", failure2.get());
}
```
{% hint style="success" %}
Unlike [`Optional::get`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#get\(\)), these methods are null-safe. However, in practice, we will not be using them frequently. Especially, since there are more convenient ways to get the success value out of a result.
{% endhint %}
## Using Alternative Success
We can use [`Result::orElse`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#orElse-S-) to provide an alternative success value that must be returned when the result is unsuccessful.
```java
@Test
void testGetOrElse() {
// Given
Result result1 = success("IDEAL");
Result result2 = failure("ERROR");
String alternative = "OTHER";
// When
String value1 = result1.orElse(alternative);
String value2 = result2.orElse(alternative);
// Then
assertEquals("IDEAL", value1);
assertEquals("OTHER", value2);
}
```
{% hint style="info" %}
Note that alternative success values can be `null`.
{% endhint %}
## Mapping Failure
The [`Result::orElseMap`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#orElseMap-java.util.function.Function-) method is similar to [`Optional::orElseGet`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#orElseGet\(java.util.function.Supplier\)), but it takes a mapping [`Function`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/function/Function.html) instead of a [`Supplier`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/function/Supplier.html). The function will receive the failure value to produce the alternative success value.
```java
@Test
void testGetOrElseMap() {
// Given
Result result1 = success("OK");
Result result2 = failure(1024);
Result result3 = failure(-256);
Function mapper = x -> x > 0 ? "HI" : "LO";
// When
String value1 = result1.orElseMap(mapper);
String value2 = result2.orElseMap(mapper);
String value3 = result3.orElseMap(mapper);
// Then
assertEquals("OK", value1);
assertEquals("HI", value2);
assertEquals("LO", value3);
}
```
{% hint style="info" %}
Although probably not the best practice, the mapping function may return `null`.
{% endhint %}
## Streaming Success or Failure
Finally, we can use [`Result::streamSuccess`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#streamSuccess--) and [`Result::streamFailure`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#streamFailure--) to wrap the value held by an instance of `Result` into a possibly-empty [`Stream`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/stream/Stream.html) object.
```java
@Test
void testStreamSuccess() {
// Given
Result result1 = success("Yes");
Result result2 = failure("No");
// When
Stream stream1 = result1.streamSuccess();
Stream stream2 = result2.streamSuccess();
// Then
assertEquals("Yes", stream1.findFirst().orElse(null));
assertNull(stream2.findFirst().orElse(null));
}
@Test
void testStreamFailure() {
// Given
Result result1 = success("Yes");
Result result2 = failure("No");
// When
Stream stream1 = result1.streamFailure();
Stream stream2 = result2.streamFailure();
// Then
assertNull(stream1.findFirst().orElse(null));
assertEquals("No", stream2.findFirst().orElse(null));
}
```
## Conclusion
We explored various ways to retrieve values from results. Using these methods you can efficiently access the underlying data within a Result object, whether it's a success or a failure.
# Conditional Actions
How to handle success and failure scenarios
We'll now delve into a set of methods that allow you to take conditional actions based on the state of a result. They provide a cleaner and more expressive way to handle success and failure scenarios, eliminating the need for lengthy *if/else* blocks.
## Handling Success
We can use [`Result::ifSuccess`](https://javadoc.io/doc/com.leakyabstractions/result-api/latest/com/leakyabstractions/result/api/Result.html#ifSuccess-java.util.function.Consumer-) to specify an action that must be executed if the result represents a successful outcome. This method takes a [consumer function](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/function/Consumer.html) that will be applied to the success value wrapped by the result.
```java
@Test
void testIfSuccess() {
// Given
List