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.

While understanding the basics provides a solid foundation, the true potential of result objects is unlocked through their functional capabilities. Mastering these techniques enables concise and readable error handling by leveraging the power of monadic composition.

This section will guide you through these powerful tools, demonstrating how to manipulate results effectively so you can craft more robust and maintainable Java applications.

Throughout these guides, we have mentioned that throwing Java exceptions is slow. But... how slow? According to our benchmarks, throwing an exception is several orders of magnitude slower than returning a failed result.

This proves that using exceptional logic just to control normal program flow is a bad idea.

Benchmarking Result Library

This library comes with a set of benchmarks that compare performance when using results versus when using exceptions.

Simple Scenarios

The first scenarios compare the most basic usage: a method that returns a String or fails, depending on a given int parameter:

Using Exceptions

public String usingExceptions(int number) throws SimpleException {
  if (number < 0) {
    throw new SimpleException(number);
  }
  return "ok";
}

Using Results

public Result<String, SimpleFailure> usingResults(int number) {
  if (number < 0) {
    return Results.failure(new SimpleFailure(number));
  }
  return Results.success("ok");
}

Complex Scenarios

The next scenarios do something a little bit more elaborate: a method invokes the previous method to retrieve a String; if successful, then converts it to upper case; otherwise transforms the "simple" error into a "complex" error.

Using Exceptions

public String usingExceptions(int number) throws ComplexException {
  try {
    return simple.usingExceptions(number).toUpperCase();
  } catch (SimpleException e) {
    throw new ComplexException(e);
  }
}

Using Results

public Result<String, ComplexFailure> usingResults(int number) {
  return simple.usingResults(number)
    .map(String::toUpperCase, ComplexFailure::new);
}

Conclusion

We provided insights into the Result library's performance through benchmarking. While our metrics corroborate that most codebases could benefit from using this library instead of throwing exceptions, its main goal is to help promote best practices and implement proper error handling.

Add-ons are optional, yet powerful extensions to the Result library, designed to provide extra features that can be integrated on demand.

These small, focused libraries provide a modular approach to extending the core functionalities of Results without adding unnecessary complexity.

The following methods allow you to run inline tests on the wrapped value of a result to dynamically transform a success into a failure or a failure into a success.

The method allows you to transform a success into a failure based on certain conditions. It takes two parameters:

1. A to determine if the success value is acceptable.

2. A mapping that will produce a failure value if the value is deemed unacceptable.

In this example, we use a lambda expression to validate that the success value inside result

This library is licensed under the Apache License, Version 2.0 (the "License"); you may not use it except in compliance with the License.

You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and limitations under the License.

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.

We can use to specify an action that must be executed if the result represents a successful outcome. This method takes a that will be applied to the success value wrapped by the result.

In this example, ifSuccess ensures that the provided action (adding the success value to the list) is only executed if the parsing operation is successful.

On the other hand, we can use method to define an action that must be taken when the result represents a failure. This method also takes a that will be applied to the failure value inside the result.

Here, ifFailure ensures that the provided action (adding the failure value to the list) is only executed if the parsing operation fails.

Tracking multiple add-on versions for your project can quickly become cumbersome. In that situation, you can use the convenient to centralize and align their versions. This ensures compatibility and simplifies dependency maintenance.

The basic idea is that instead of specifying a version number for each Result library in your project, you can use this BOM to get a complete set of consistent versions.

Add this Maven dependency to your build:

To help you become familiar with this library, you can explore two demo projects that showcase how to handle and serialize Result objects within popular frameworks like and . Each project provides a working example of a "pet store" web service that exposes a REST API for managing pets. They are based on and you can interact with them using .

These projects illustrate how to develop powerful APIs using Result objects. Follow the examples to create resilient web services that elegantly handle success and failure scenarios.

Wave goodbye to slow exceptions and embrace clean, efficient error handling by encapsulating operations that may succeed or fail in a type-safe way.

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.

As we discovered earlier, we can easily determine if a given Result instance is successful or not.

Checking Success

We can use Result::hasSuccess to obtain a boolean value that represents whether a result is successful.

Checking Failure

We can also use Result::hasFailure to find out if a result contains a failure value.

Conclusion

We discussed how to determine the state of a Result object using hasSuccess and hasFailure. These methods provide a straightforward way to identify the outcome of an operation, helping you make decisions based on the outcome.

This library adheres to Pragmatic Versioning to communicate the backwards compatibility of each version.

The latest releases are available in

Result supports both Maven and Gradle for seamless integration into your Java build workflow.

Artifact Coordinates

Add this Maven dependency to your build:

Add Result as a Maven dependency to your project.

Add Result as a Gradle dependency to your project.

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.

This demo project demonstrates how to handle and serialize Result objects within a Micronaut application. It provides a working example of a "pet store" web service that exposes a REST API for managing pets.

Generating the Project

The project was generated via Micronaut Launch including features: annotation-api, http-client, openapi, serialization-jackson, swagger-ui, toml, and validation.

Adding Serialization Support

Then Micronaut Serialization for Result objects was manually added as a dependency to serialize and deserialize Result objects.

dependencies {
    // ...
    implementation(platform("com.leakyabstractions:result-bom:1.0.0.0"))
    implementation("com.leakyabstractions:result")
    implementation("com.leakyabstractions:result-micronaut-serde")
}

That's all we need to do to make Micronaut treat results as Serdeable.

API Responses

API responses contain a Result field, encapsulating the outcome of the requested operation.

Results have different success types, depending on the specific endpoint. Failures will be encapsulated as instances of ApiError.

Controllers return instances of ApiResponse that will be serialized to JSON by Micronaut:

Since failures are expressed as ApiError objects, endpoints invariably return HTTP status 200.

The application can be built and run with Gradle.

This will start a stand-alone server on port 8080.

Once started, you can interact with the API.

You should see a JSON response like this:

You can navigate to to inspect the API using an interactive UI.

Result builds upon the familiar concept of Optional, enhancing it with the ability to represent both success and failure states.

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.

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.

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().

You can use fluent assertions for Result objects to enhance the readability and expressiveness of your unit tests. These assertions are based on AssertJ, an open-source Java library that offers a fluent API for writing assertions in test cases.

How to Use this Add-On

Add this Maven dependency to your build:

You can use in your tests to create fluent assertions for result objects.

If, for any reason, you cannot statically import assertThat, you can use instead.

We covered how to use fluent assertions for Results. This approach allows you to write clear and expressive tests, enhancing the maintainability of your unit tests while ensuring that Result objects behave as expected.

Congratulations on reaching the end of this guide! By now, you should have a solid understanding of how to use results in your Java applications effectively. Here's a brief recap of what you've learned:

• Getting Started: You learned how to integrate result objects into your codebase and instantiate new ones.

• Basic Usage: You explored foundational operations like checking statuses, unwrapping values, and executing conditional actions based on result status, enabling you to respond dynamically to success and failure scenarios.

• Advanced Usage: You delved into more sophisticated techniques like screening results to transform successes and failures based on conditions, and leveraging mapping and flat-mapping methods to compose behaviors in a functional style.

For more details on the Result API, you can read the .

Next, we'll introduce additional resources where you can further enhance your understanding and skills. Let's continue expanding your knowledge!

There are several ways to create result objects.

A successful result contains a non-null value produced by an operation when everything works as intended. We can use to create a new instance.

On the other hand, a failed result holds a value representing the problem that prevented the operation from completing. We can use to create a new one.

When we need to create results that depend on a possibly null value, we can use . If the first argument is null, then the second one will be used to create a failed result.

We can also use to create results that depend on an value. If the first argument is an empty optional, then the second one will be used to create a failed result.

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 so we don't need to use a try-catch block.

This demo project demonstrates how to handle and serialize Result objects within a application. It provides a working example of a "pet store" web service that exposes a REST API for managing pets.

The project was generated via including features: web and cloud-feign.

Then was manually added as a dependency to serialize and deserialize Result objects.

We use a @Bean to register the datatype module.

API responses contain a Result field, encapsulating the outcome of the requested operation.

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.

Unwrapping Success

The most basic way to retrieve the success value wrapped inside a result is by using Result::getSuccess. This method will return an optional success value, depending on whether the result was actually successful or not.

@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 to obtain the failure value held by a Result object.

@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());
}

Using Alternative Success

We can use Result::orElse to provide an alternative success value that must be returned when the result is unsuccessful.

@Test
void testGetOrElse() {
  // Given
  Result<String, String> result1 = success("IDEAL");
  Result<String, String> result2 = failure("ERROR");
  String alternative = "OTHER";
  // When
  String value1 = result1.orElse(alternative);
  String value2 = result2.orElse(alternative);
  // Then
  assertEquals("IDEAL", value1);
  assertEquals("OTHER", value2);
}

Mapping Failure

The Result::orElseMap method is similar to Optional::orElseGet, but it takes a mapping Function instead of a Supplier. The function will receive the failure value to produce the alternative success value.

@Test
void testGetOrElseMap() {
  // Given
  Result<String, Integer> result1 = success("OK");
  Result<String, Integer> result2 = failure(1024);
  Result<String, Integer> result3 = failure(-256);
  Function<Integer, String> 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);
}

Streaming Success or Failure

Finally, we can use Result::streamSuccess and to wrap the value held by an instance of Result into a possibly-empty object.

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.

Transforming result objects is a key feature that enables you to compose complex operations in a clean and functional style. There are two primary techniques used for these transformations.

Mapping Results

Mapping involves applying a function to the value inside a result to produce a new result object.

Mapping Success Values

We can use Result::mapSuccess to apply a function to the success value of a result, transforming it into a new success value. If the result is a failure, it remains unchanged.

@Test
void testMapSuccess() {
  // Given
  Result<String, ?> result = success("HELLO");
  // When
  Result<Integer, ?> mapped = result.mapSuccess(String::length);
  // Then
  assertEquals(5, mapped.orElse(null));
}

In this example, we wrap a String inside a Result object and invoke mapSuccess to calculate its length and wrap it inside a new Result object.

Mapping Failure Values

Next up, we can use Result::mapFailure to apply a function to the failure value, transforming it into a new one. If the result is a success, it remains unchanged.

@Test
void testMapFailure() {
  // Given
  Result<?, BigDecimal> result = failure(ONE);
  // When
  Result<?, Boolean> mapped = result.mapFailure(TWO::equals);
  // Then
  assertFalse(mapped.getFailure().orElse(null));
}

Here, we invoke mapFailure to transform the failure type of the result from String to Boolean for demonstration purposes.

The method simultaneously handles both success and failure cases by applying two separate functions: one for transforming the success value and one for transforming the failure value.

Flat-mapping is used to chain operations that return results themselves, flattening the nested structures into a single result object. This allows you to transform a success into a failure, or a failure into a success.

To illustrate flat-mapping concepts, the next examples will follow a familiar "pet store" theme. This involves three Java types: Pet, PetError, and PetStore. These types will help us demonstrate the effective use of flat-mapping methods.

With these types defined, we'll explore how to use various flat-mapping methods to transform result objects and manage pet-related operations in our imaginary pet store.

Use to chain an operation that returns a result object. This method applies a mapping function to the success value, replacing the original result with the new one returned by the function. If the result is a failure, it remains unchanged.

This example starts with a successful result containing a wrong pet ID (not found in the pet store). When we flat-map it with the store's find method reference, the final result contains a pet error.

Use to chain a result-bearing operation. This method also replaces the original result with the new one returned by the mapping function. If the result is a success, it remains unchanged.

Here we start with a failed result containing a pet error. When we flat-map it with the store's getDefaultPetId method reference, the final result contains the ID of the default pet in the store.

The method handles both success and failure cases by applying the appropriate function based on the status of the original result.

This example starts with a successful result containing a wrong pet ID (not found in the pet store). When we flat-map it with the store's find method reference, the final result contains a pet error.

Here we start with a failed result containing a pet error. When we flat-map it with the store's getDefaultPetId method reference, the final result contains the ID of the default pet in the store.

We demonstrated how to transform results in a concise and functional manner, enhancing the clarity and flexibility of your error-handling and data-processing logic.

When using Result objects with Micronaut, we might run into some problems. The Micronaut serialization support for Result solves them by making Micronaut treat results as Serdeable (so they can be serialized and deserialized).

How to Use this Add-On

Add this Maven dependency to your build:

Let's start by creating a record ApiOperation containing one ordinary and one Result field.

We will take a look at what happens when we try to serialize and deserialize ApiOperation objects with Micronaut.

Now, let's create a Micronaut controller that returns an instance of ApiOperation containing a successful result.

And finally, let's run the application and try the /operations/last endpoint we just created.

We'll see that we get a Micronaut CodecException caused by a .

Although this may look strange, it's actually what we should expect. Even though we annotated ApiOperation as , Micronaut doesn't know how to serialize result objects yet, so the data structure cannot be serialized.

This is Micronaut's default serialization behavior. But we'd like to serialize the result field like this:

Now, let's reverse our previous example, this time trying to receive an ApiOperation as the body of a POST request.

We'll see that now we get an . Let's inspect the stack trace.

This behavior again makes sense. Essentially, Micronaut cannot create new result objects, because Result is not annotated as or .

What we want, is for Micronaut to treat Result values as JSON objects that contain either a success or a failure value. Fortunately, there's an easy way to solve this problem.

All we need to do now is . Once the is in the classpath, all functionality is available for all normal Micronaut operations.

Now, let's try and serialize our ApiOperation object again.

If we look at the serialized response, we'll see that this time the result field contains a success field.

Next, we can try serializing a failed result.

We can verify that the serialized response contains a non-null failure value and a null success value:

Now, let's repeat our tests for deserialization. If we read our ApiOperation again, we'll see that we no longer get an .

Finally, let's repeat the test again, this time with a failed result. We'll see that yet again we don't get an exception, and in fact, have a failed result.

We learned how to serialize and deserialize Result objects using , demonstrating how the provided enables Micronaut to treat Results as objects.

When using Result objects with Jackson we might run into some problems. The Jackson datatype modules for Result solve them by making Jackson treat results as if they were ordinary objects.

How to Use These Add-Ons

Choose the Maven dependency that matches your Jackson version.

Jackson 2.x

Add this Maven dependency to your build:

Add this one instead:

Let's start by creating a class ApiResponse containing one ordinary and one Result field.

Then we will take a look at what happens when we try to serialize and deserialize ApiResponse objects.

Now, let's instantiate an ApiResponse object.

And finally, let's try serializing it using an .

With Jackson 2.x, this will produce an error: .

The reason is Jackson encounters Optional values internally and it will not handle it unless you register .

Now, let's reverse our previous example, this time trying to deserialize a JSON object into an ApiResponse.

This will produce an error: . Let's inspect the stack trace.

This behavior again makes sense. Essentially, Jackson cannot create new result objects because Result is an interface, not a concrete type.

The Jackson datatype modules for Result provide serializers and deserializers so that Jackson treats results as if they were regular objects.

First of all, we need to .

Then, all we need to do is register ResultModule with our .

Alternatively, you can also make Jackson 2.x auto-discover the module.

Just like the previous example, we need to add ResultModule to our .

Or simply use auto-discovery:

Now, let's try and serialize our ApiResponse object again:

If we look at the serialized response, we'll see that this time the result field contains a null failure value and a non-null success value:

Next, we can try serializing a failed result.

We can verify that the serialized response contains a non-null failure value and a null success value.

Now, let's repeat our tests for deserialization. If we read our ApiResponse again, we'll see that we no longer get an .

Finally, let's repeat the test again, this time with a failed result. We'll see that yet again we don't get an exception, and in fact, have a failed result.

We learned how to serialize and deserialize Result objects using both Jackson 2.x and Jackson 2.x, demonstrating how the provided datatype module enables Jackson to treat Results as ordinary objects.

The integration is nearly identical across versions; the main differences are limited to dependency coordinates and how the object mapper is constructed and configured.

Lazy results optimize performance by deferring costly operations until absolutely necessary. They behave like regular results, but only execute the underlying operation when an actual check for success or failure is performed.

Add this Maven dependency to your build: