1 of 25

Result Library for Java

Introduction

A Java library to handle success and failure without exceptions

A library to handle success and failure 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.

Result objects represent the outcome of an operation, removing the need to check for null. Operations that succeed produce results encapsulating a success value; operations that fail produce results with a failure value. Success and failure can be represented by whatever types make the most sense for each operation.

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.

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

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.

Ready to Tap into the Power of Results?

Read the guide and transform your error handling today.

TL;DR

Using the Library

Getting Started

How to get up and running with Results in no time

The best way to think of Results is as a super-powered version of Java's Optionals.

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

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.

Results provide the same methods as Optionals, plus additional ones to handle failure states effectively.

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.

Adding Result to Your Build

How to add Result as a dependency to your build

Artifact Coordinates

Add this Maven dependency to your build:

Group ID

Artifact ID

Latest Version

com.leakyabstractions

result

Maven

<dependencies>
    <dependency>
        <groupId>com.leakyabstractions</groupId>
        <artifactId>result</artifactId>
        <version>1.0.0.0</version>
    </dependency>
</dependencies>

Gradle

dependencies {
    implementation("com.leakyabstractions:result:1.0.0.0")
}

Conclusion

Creating Results

How to instantiate new Result objects

There are several ways to create result objects.

Successful Results

@Test
void testSuccess() {
  // When
  Result<Integer, ?> result = Results.success(200);
  // Then
  assertTrue(result::hasSuccess);
  assertFalse(result::hasFailure);
}

Failed Results

@Test
void testFailure() {
  // When
  Result<?, String> result = Results.failure("The operation failed");
  // Then
  assertTrue(result::hasFailure);
  assertFalse(result::hasSuccess);
}

Failure values cannot be null either.

Results Based on Nullable Values

@Test
void testOfNullable() {
  // Given
  String string1 = "The operation succeeded";
  String string2 = null;
  // When
  Result<String, Integer> result1 = Results.ofNullable(string1, 404);
  Result<String, Integer> result2 = Results.ofNullable(string2, 404);
  // Then
  assertTrue(result1::hasSuccess);
  assertTrue(result2::hasFailure);
}

The second argument can be either a failure value or a function that produces a failure value.

Results Based on Optionals

@Test
void testOfOptional() {
  // Given
  Optional<BigDecimal> optional1 = Optional.of(BigDecimal.ONE);
  Optional<BigDecimal> optional2 = Optional.empty();
  // When
  Result<BigDecimal, Integer> result1 = Results.ofOptional(optional1, -1);
  Result<BigDecimal, Integer> result2 = Results.ofOptional(optional2, -1);
  // Then
  assertTrue(result1::hasSuccess);
  assertTrue(result2::hasFailure);
}

Results Based on Callables

String task1() {
  return "OK";
}

String task2() throws Exception {
  throw new Exception("Whoops!");
}

@Test
void testOfCallable() {
  // When
  Result<String, Exception> result1 = Results.ofCallable(this::task1);
  Result<String, Exception> result2 = Results.ofCallable(this::task2);
  // Then
  assertTrue(result1::hasSuccess);
  assertTrue(result2::hasFailure);
}

This method enables compatibility with legacy or third-party code that uses exceptions to indicate operation failure.

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.

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

@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

@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

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.

As useful as this may seem, we will soon realize that we won't be doing it very often.

Unwrapping Success

@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

@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

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

Note that alternative success values can be null.

Mapping Failure

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

Although probably not the best practice, the mapping function may return null.

Streaming Success or Failure

@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

@Test
void testIfSuccess() {
  // Given
  List<Object> list = new ArrayList<>();
  Result<Integer, String> result = success(100);
  // When
  result.ifSuccess(list::add);
  // Then
  assertEquals(100, list.getFirst());
}

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.

Handling Failure

@Test
void testIfFailure() {
  // Given
  List<Object> list = new ArrayList<>();
  Result<Integer, String> result = failure("ERROR");
  // When
  result.ifFailure(list::add);
  // Then
  assertEquals("ERROR", list.getFirst());
}

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

Handling Both Scenarios

@Test
void testIfSuccessOrElse() {
  // Given
  List<Object> list1 = new ArrayList<>();
  List<Object> list2 = new ArrayList<>();
  Result<Long, String> result1 = success(100L);
  Result<Long, String> result2 = failure("ERROR");
  // When
  result1.ifSuccessOrElse(list1::add, list1::add);
  result2.ifSuccessOrElse(list2::add, list2::add);
  // Then
  assertEquals(100L, list1.getFirst());
  assertEquals("ERROR", list2.getFirst());
}

In this example, ifSuccessOrElse simplifies conditional logic by providing a single method to handle both success and failure scenarios, making the code more concise and readable.

Conclusion

We explained how to handle success and failure scenarios using these three methods. They provide a powerful way to perform conditional actions based on the state of a Result, streamlining your error handling and making your code more readable and maintainable.

Screening Results

How to reject success values and accept failure values

Screening mechanisms provide greater flexibility in handling edge cases and enable more robust error recovery strategies.

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.

Validating Success

This can be used to enforce additional validation constraints on success values.

@Test
void testFilter() {
  // Given
  Result<Integer, String> result = success(1);
  // When
  Result<Integer, String> filtered = result.filter(x -> x % 2 == 0, x -> "It's odd");
  // Then
  assertTrue(filtered.hasFailure());
}

In this example, we use a lambda expression to validate that the success value inside result is even. Since the number is odd, it transforms the result into a failure.

Note that it is illegal for the mapping function to return null.

Recovering From Failure

This method is useful for implementing fallback mechanisms or recovery strategies, ensuring the application logic remains resilient and adaptable.

@Test
void testRecover() {
  // Given
  Result<Integer, String> result = failure("OK");
  // When
  Result<Integer, String> filtered = result.recover("OK"::equals, String::length);
  // Then
  assertTrue(filtered.hasSuccess());
}

In this example, we use method references to check if the failure value equals OK and then transform the result into a success.

Conclusion

Transforming Results

How to transform values wrapped inside Results

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

@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

@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.

Mapping Both Success and Failure

@Test
void testMap() {
  // Given
  Result<String, BigDecimal> result1 = success("HELLO");
  Result<String, BigDecimal> result2 = failure(ONE);
  // When
  Result<Integer, Boolean> mapped1 = result1.map(String::length, TWO::equals);
  Result<Integer, Boolean> mapped2 = result2.map(String::length, TWO::equals);
  // Then
  assertEquals(5, mapped1.orElse(null));
  assertFalse(mapped2.getFailure().orElse(null));
}

Flat-Mapping Results

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.

enum PetError {NOT_FOUND, NO_CONFIG}

record Pet(long id, String name) {

  static final Pet DEFAULT = new Pet(0, "Default pet");
  static final Pet ROCKY = new Pet(1, "Rocky");
  static final Pet GARFIELD = new Pet(2, "Garfield");
}

record PetStore(Pet... pets) {

  PetStore() {
    this(Pet.ROCKY, Pet.GARFIELD);
  }

  Result<Pet, PetError> find(long id) {
    Optional<Pet> found = stream(pets).filter(pet -> pet.id() == id).findAny();
    return Results.ofOptional(found, NOT_FOUND);
  }

  Result<Pet, PetError> getDefaultPet(PetError error) {
    return error == NO_CONFIG ? success(Pet.DEFAULT) : failure(error);
  }

  Result<Long, PetError> getDefaultPetId(PetError error) {
    return getDefaultPet(error).mapSuccess(Pet::id);
  }
}

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.

Flat-Mapping Successful Results

@Test
void testFlatMapSuccess() {
  // Given
  PetStore store = new PetStore();
  Result<Long, PetError> result = success(100L);
  // When
  Result<Pet, PetError> mapped = result.flatMapSuccess(store::find);
  // Then
  assertEquals(NOT_FOUND, mapped.getFailure().orElse(null));
}

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.

Flat-Mapping Failed Results

@Test
void testFlatMapFailure() {
  // Given
  PetStore store = new PetStore();
  Result<Long, PetError> result = failure(NO_CONFIG);
  // When
  Result<Long, PetError> mapped = result.flatMapFailure(store::getDefaultPetId);
  // Then
  assertEquals(Pet.DEFAULT.id(), mapped.orElse(null));
}

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.

Flat-Mapping Both Success and Failure

@Test
void testFlatMap() {
  // Given
  PetStore store = new PetStore();
  Result<Long, PetError> result1 = success(100L);
  Result<Long, PetError> result2 = failure(NO_CONFIG);
  // When
  Result<Pet, PetError> mapped1 = result1.flatMap(store::find, store::getDefaultPet);
  Result<Pet, PetError> mapped2 = result2.flatMap(store::find, store::getDefaultPet);
  // Then
  assertEquals(NOT_FOUND, mapped1.getFailure().orElse(null));
  assertEquals(Pet.DEFAULT, mapped2.orElse(null));
}

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.

Conclusion

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.

Add-ons

Lazy Results

How to defer expensive calculations with Results

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.

How to Use this Add-On

Add this Maven dependency to your build:

Group ID

Artifact ID

Latest Version

com.leakyabstractions

result-lazy

Creating Lazy Results

Supplier<Result<Integer, String>> supplier = () -> success(123);
Result<Integer, String> lazy = LazyResults.ofSupplier(supplier);

/* Represents the operation we may omit */
Result<Long, Exception> expensiveCalculation(AtomicLong timesExecuted) {
  long counter = timesExecuted.incrementAndGet();
  return success(counter);
}

This sample method simply increments and returns a counter for brevity. However, in a typical scenario, this would involve an I/O operation.

Skipping Expensive Calculations

@Test
void shouldSkipExpensiveCalculation() {
  AtomicLong timesExecuted = new AtomicLong();
  // Given
  Result<Long, Exception> lazy = LazyResults
      .ofSupplier(() -> expensiveCalculation(timesExecuted));
  // When
  Result<String, Exception> transformed = lazy.mapSuccess(Object::toString);
  // Then
  assertNotNull(transformed);
  assertEquals(0L, timesExecuted.get());
}

In this example, the expensive calculation is omitted because the lazy result is never fully evaluated. This test demonstrates that a lazy result can be transformed while maintaining laziness, ensuring that the expensive calculation is deferred.

These methods will preserve laziness:

Triggering Result Evaluation

@Test
void shouldExecuteExpensiveCalculation() {
  AtomicLong timesExecuted = new AtomicLong();
  // Given
  Result<Long, Exception> lazy = LazyResults
      .ofSupplier(() -> expensiveCalculation(timesExecuted));
  // When
  Result<String, Exception> transformed = lazy.mapSuccess(Object::toString);
  boolean success = transformed.hasSuccess();
  // Then
  assertTrue(success);
  assertEquals(1L, timesExecuted.get());
}

Here, the expensive calculation is executed because the lazy result is finally evaluated.

Terminal methods will immediately evaluate the lazy result:

Handling Success and Failure Eagerly

@Test
void shouldHandleSuccessEagerly() {
  AtomicLong timesExecuted = new AtomicLong();
  AtomicLong consumerExecuted = new AtomicLong();
  Consumer<Long> consumer = x -> consumerExecuted.incrementAndGet();
  // Given
  Result<Long, Exception> lazy = LazyResults
      .ofSupplier(() -> expensiveCalculation(timesExecuted));
  // When
  lazy.ifSuccess(consumer);
  // Then
  assertEquals(1L, timesExecuted.get());
  assertEquals(1L, consumerExecuted.get());
}

In this test, we don't explicitly unwrap the value or check the status, but since we want to consume the success value, we need to evaluate the lazy result first.

Furthermore, even if we wanted to handle the failure scenario, we would still need to evaluate the lazy result.

@Test
void shouldHandleFailureEagerly() {
  AtomicLong timesExecuted = new AtomicLong();
  AtomicLong consumerExecuted = new AtomicLong();
  Consumer<Exception> consumer = x -> consumerExecuted.incrementAndGet();
  // Given
  Result<Long, Exception> lazy = LazyResults
      .ofSupplier(() -> expensiveCalculation(timesExecuted));
  // When
  lazy.ifFailure(consumer);
  // Then
  assertEquals(1L, timesExecuted.get());
  assertEquals(0L, consumerExecuted.get());
}

These methods are treated as terminal when used with regular consumer functions:

Handling Success and Failure Lazily

@Test
void shouldHandleSuccessLazily() {
  AtomicLong timesExecuted = new AtomicLong();
  AtomicLong consumerExecuted = new AtomicLong();
  Consumer<Long> consumer = LazyConsumer
      .of(x -> consumerExecuted.incrementAndGet());
  // Given
  Result<Long, Exception> lazy = LazyResults
      .ofSupplier(() -> expensiveCalculation(timesExecuted));
  // When
  lazy.ifSuccess(consumer);
  // Then
  assertEquals(0L, timesExecuted.get());
  assertEquals(0L, consumerExecuted.get());
}

Conclusion

We learned how to defer expensive calculations until absolutely necessary. By leveraging lazy results, you can optimize performance by avoiding unnecessary computations and only evaluating the operation's outcome when needed.

Fluent Assertions

How to assert Result objects fluently

How to Use this Add-On

Add this Maven dependency to your build:

Group ID

Artifact ID

Latest Version

com.leakyabstractions

result-assertj

Asserting Result Objects

import static com.leakyabstractions.result.assertj.ResultAssertions.assertThat;

@Test
void testAssertThat() {
  // Given
  final int zero = 0;
  // When
  final Result<Integer, String> result = success(zero);
  // Then
  assertThat(zero).isZero();
  assertThat(result).hasSuccess(zero);
}

import static com.leakyabstractions.result.assertj.ResultAssert.assertThatResult;
import static org.assertj.core.api.Assertions.assertThat;

@Test
void testAssertThatResult() {
  // Given
  final int zero = 0;
  // When
  final Result<Integer, String> result = success(zero);
  // Then
  assertThat(zero).isZero();
  assertThatResult(result).hasSuccess(zero);
}

Conclusion

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.

Jackson Module

How to serialize Result objects with Jackson

How to Use this Add-On

Add this Maven dependency to your build:

Group ID

Artifact ID

Latest Version

com.leakyabstractions

result-jackson

Test Scenario

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

/** Represents an API response */
public class ApiResponse {

  @JsonProperty
  String version;

  @JsonProperty
  Result<String, String> result;

  // Constructors, getters and setters omitted
}

Problem Overview

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

Serialization Problem

Now, let's instantiate an ApiResponse object.

ApiResponse response = new ApiResponse();
response.setVersion("v1");
response.setResult(success("Perfect"));

ObjectMapper objectMapper = new ObjectMapper();
String json = objectMapper.writeValueAsString(response);

Java 8 optional type `java.util.Optional<java.lang.String>`
 not supported by default:
 add Module "com.fasterxml.jackson.datatype:jackson-datatype-jdk8"
 to enable handling

@Test
void testSerializationProblem() {
  // Given
  ApiResponse response = new ApiResponse("v1", success("Perfect"));
  // Then
  ObjectMapper objectMapper = new ObjectMapper();
  InvalidDefinitionException error = assertThrows(InvalidDefinitionException.class,
      () -> objectMapper.writeValueAsString(response));
  assertTrue(error.getMessage().startsWith(
      "Java 8 optional type `java.util.Optional<java.lang.String>` not supported"));
}

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

{
  "version": "v1",
  "result": {
    "failure": null,
    "success": "Perfect"
  }
}

Deserialization Problem

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

String json = "{\"version\":\"v2\",\"result\":{\"success\":\"OK\"}}";
ObjectMapper objectMapper = new ObjectMapper();
objectMapper.readValue(json, ApiResponse.class);

Cannot construct instance of `com.leakyabstractions.result.api.Result`
 (no Creators, like default constructor, exist):
 abstract types either need to be mapped to concrete types,
 have custom deserializer, or contain additional type information

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

@Test
void testDeserializationProblem() {
  // Given
  String json = "{\"version\":\"v2\",\"result\":{\"success\":\"OK\"}}";
  // Then
  ObjectMapper objectMapper = new ObjectMapper();
  InvalidDefinitionException error = assertThrows(InvalidDefinitionException.class,
      () -> objectMapper.readValue(json, ApiResponse.class));
  assertTrue(error.getMessage().startsWith(
      "Cannot construct instance of `com.leakyabstractions.result.api.Result`"));
}

Solution Implementation

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

Registering the Jackson Datatype Module for Result

ObjectMapper objectMapper = new ObjectMapper();
objectMapper.registerModule(new ResultModule());

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

objectMapper.findAndRegisterModules();

Regardless of the chosen registration mechanism, once the module is registered all functionality is available for all normal Jackson operations.

Serializing Results

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

@Test
void serializeSuccessfulResult() throws Exception {
  // Given
  ApiResponse response = new ApiResponse("v3", success("All good"));
  // When
  ObjectMapper objectMapper = new ObjectMapper();
  objectMapper.registerModule(new ResultModule());
  String json = objectMapper.writeValueAsString(response);
  // Then
  assertTrue(json.contains("v3"));
  assertTrue(json.contains("All good"));
}

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:

{
  "version": "v3",
  "result": {
    "failure": null,
    "success": "All good"
  }
}

Next, we can try serializing a failed result.

@Test
void serializeFailedResult() throws Exception {
  // Given
  ApiResponse response = new ApiResponse("v4", failure("Oops"));
  // When
  ObjectMapper objectMapper = new ObjectMapper();
  objectMapper.findAndRegisterModules();
  String json = objectMapper.writeValueAsString(response);
  // Then
  assertTrue(json.contains("v4"));
  assertTrue(json.contains("Oops"));
} // End

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

{
  "version": "v4",
  "result": {
    "failure": "Oops",
    "success": null
  }
}

Deserializing Results

@Test
void deserializeSuccessfulResult() throws Exception {
  // Given
  String json = "{\"version\":\"v5\",\"result\":{\"success\":\"Yay\"}}";
  // When
  ObjectMapper objectMapper = new ObjectMapper().findAndRegisterModules();
  ApiResponse response = objectMapper.readValue(json, ApiResponse.class);
  // Then
  assertEquals("v5", response.getVersion());
  assertEquals("Yay", response.getResult().orElse(null));
}

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.

@Test
void deserializeFailedResult() throws Exception {
  // Given
  String json = "{\"version\":\"v6\",\"result\":{\"failure\":\"Nay\"}}";
  // When
  ObjectMapper objectMapper = new ObjectMapper().findAndRegisterModules();
  ApiResponse response = objectMapper.readValue(json, ApiResponse.class);
  // Then
  assertEquals("v6", response.getVersion());
  assertEquals("Nay", response.getResult().getFailure().orElse(null));
}

Conclusion

Other resources

Benchmarks

Measuring performance to find out how fast Results are

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.

We should throw exceptions sparingly, even more so when developing performance-critical applications.

Benchmarking Result Library

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.

To address performance concerns, benchmark your applications to gain reusable insights. These should guide your decisions on selecting frameworks and libraries.

Jackson Module

How to serialize Result objects with Jackson

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

is a Java library for parsing and generation. It is widely used for converting Java objects to JSON and vice versa, making it essential for handling data in web services and RESTful APIs.

How to Use this Add-On

Add this Maven dependency to your build:

Group ID

Artifact ID

Latest Version

com.leakyabstractions

result-jackson

provides snippets for different build tools to declare this dependency.

Test Scenario

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

/** Represents an API response */
public class ApiResponse {

  @JsonProperty
  String version;

  @JsonProperty
  Result<String, String> result;

  // Constructors, getters and setters omitted
}

Problem Overview

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

Serialization Problem

Now, let's instantiate an ApiResponse object.

ApiResponse response = new ApiResponse();
response.setVersion("v1");
response.setResult(success("Perfect"));

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

ObjectMapper objectMapper = new ObjectMapper();
String json = objectMapper.writeValueAsString(response);

We'll see that now we get an .

Java 8 optional type `java.util.Optional<java.lang.String>`
 not supported by default:
 add Module "com.fasterxml.jackson.datatype:jackson-datatype-jdk8"
 to enable handling

While this may look strange, it's the expected behavior. When Jackson examined the result object, it invoked and received an optional string value. But Jackson will not handle JDK 8 datatypes like Optional unless you register .

@Test
void testSerializationProblem() {
  // Given
  ApiResponse response = new ApiResponse("v1", success("Perfect"));
  // Then
  ObjectMapper objectMapper = new ObjectMapper();
  InvalidDefinitionException error = assertThrows(InvalidDefinitionException.class,
      () -> objectMapper.writeValueAsString(response));
  assertTrue(error.getMessage().startsWith(
      "Java 8 optional type `java.util.Optional<java.lang.String>` not supported"));
}

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

{
  "version": "v1",
  "result": {
    "failure": null,
    "success": "Perfect"
  }
}

Deserialization Problem

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

String json = "{\"version\":\"v2\",\"result\":{\"success\":\"OK\"}}";
ObjectMapper objectMapper = new ObjectMapper();
objectMapper.readValue(json, ApiResponse.class);

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

Cannot construct instance of `com.leakyabstractions.result.api.Result`
 (no Creators, like default constructor, exist):
 abstract types either need to be mapped to concrete types,
 have custom deserializer, or contain additional type information

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

@Test
void testDeserializationProblem() {
  // Given
  String json = "{\"version\":\"v2\",\"result\":{\"success\":\"OK\"}}";
  // Then
  ObjectMapper objectMapper = new ObjectMapper();
  InvalidDefinitionException error = assertThrows(InvalidDefinitionException.class,
      () -> objectMapper.readValue(json, ApiResponse.class));
  assertTrue(error.getMessage().startsWith(
      "Cannot construct instance of `com.leakyabstractions.result.api.Result`"));
}

Solution Implementation

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

Registering the Jackson Datatype Module for Result

Once we have , all we need to do is register ResultModule with our object mapper.

ObjectMapper objectMapper = new ObjectMapper();
objectMapper.registerModule(new ResultModule());

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

objectMapper.findAndRegisterModules();

Regardless of the chosen registration mechanism, once the module is registered all functionality is available for all normal Jackson operations.

Serializing Results

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

@Test
void serializeSuccessfulResult() throws Exception {
  // Given
  ApiResponse response = new ApiResponse("v3", success("All good"));
  // When
  ObjectMapper objectMapper = new ObjectMapper();
  objectMapper.registerModule(new ResultModule());
  String json = objectMapper.writeValueAsString(response);
  // Then
  assertTrue(json.contains("v3"));
  assertTrue(json.contains("All good"));
}

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:

{
  "version": "v3",
  "result": {
    "failure": null,
    "success": "All good"
  }
}

Next, we can try serializing a failed result.

@Test
void serializeFailedResult() throws Exception {
  // Given
  ApiResponse response = new ApiResponse("v4", failure("Oops"));
  // When
  ObjectMapper objectMapper = new ObjectMapper();
  objectMapper.findAndRegisterModules();
  String json = objectMapper.writeValueAsString(response);
  // Then
  assertTrue(json.contains("v4"));
  assertTrue(json.contains("Oops"));
} // End

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

{
  "version": "v4",
  "result": {
    "failure": "Oops",
    "success": null
  }
}

Deserializing Results

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

@Test
void deserializeSuccessfulResult() throws Exception {
  // Given
  String json = "{\"version\":\"v5\",\"result\":{\"success\":\"Yay\"}}";
  // When
  ObjectMapper objectMapper = new ObjectMapper().findAndRegisterModules();
  ApiResponse response = objectMapper.readValue(json, ApiResponse.class);
  // Then
  assertEquals("v5", response.getVersion());
  assertEquals("Yay", response.getResult().orElse(null));
}

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.

@Test
void deserializeFailedResult() throws Exception {
  // Given
  String json = "{\"version\":\"v6\",\"result\":{\"failure\":\"Nay\"}}";
  // When
  ObjectMapper objectMapper = new ObjectMapper().findAndRegisterModules();
  ApiResponse response = objectMapper.readValue(json, ApiResponse.class);
  // Then
  assertEquals("v6", response.getVersion());
  assertEquals("Nay", response.getResult().getFailure().orElse(null));
}

Conclusion

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

The full source code for the examples is .

Micronaut Serialization

How to serialize Result objects with Micronaut

How to Use this Add-On

Add this Maven dependency to your build:

Group ID

Artifact ID

Latest Version

com.leakyabstractions

result-micronaut-serde

Test Scenario

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

/** Represents an API operation */
@Serdeable
public record ApiOperation(String name, Result<String, String> result) {
}

Problem Overview

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

Serialization Problem

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

@Controller("/operations")
public class ApiController {

    @Get("/last")
    ApiOperation lastOperation() {
        return new ApiOperation("setup", Results.success("Perfect"));
    }
}

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

curl 'http://localhost:8080/operations/last'

No serializable introspection present for type Success.
 Consider adding Serdeable. Serializable annotate to type Success.
 Alternatively if you are not in control of the project's source code,
 you can use @SerdeImport(Success.class) to enable serialization of this type.

@Test
void testSerializationProblem(ObjectMapper objectMapper) {
  // Given
  ApiOperation op = new ApiOperation("setup", success("Perfect"));
  // Then
  SerdeException error = assertThrows(SerdeException.class,
      () -> objectMapper.writeValueAsString(op));
  assertTrue(error.getMessage().startsWith(
      "No serializable introspection present for type Success."));
}

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

{
  "name": "setup",
  "result": {
    "failure": null,
    "success": "Perfect"
  }
}

Deserialization Problem

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

@Controller("/operations")
public class ApiController {

    @Post("/notify")
    Map<String, String> notify(@Body ApiOperation op) {
        return op.result()
                .mapSuccess(s -> Map.of("message", op.name() + " succeeded: " + s))
                .orElseMap(f -> Map.of("error", op.name() + " failed: " + f));
    }
}

No bean introspection available for type
 [interface com.leakyabstractions.result.api.Result].
 Ensure the class is annotated with
 io.micronaut.core.annotation.Introspected

@Test
void testDeserializationProblem(ObjectMapper objectMapper) {
  // Given
  String json = """
      {"name":"renew","result":{"success":"OK"}}""";
  // Then
  IntrospectionException error = assertThrows(IntrospectionException.class,
      () -> objectMapper.readValue(json, ApiOperation.class));
  String errorMessage = error.getMessage(); // Extract error message
  // Verify error message
  assertTrue(errorMessage.startsWith("No bean introspection available " +
      "for type [interface com.leakyabstractions.result.api.Result]."));
} // End

Solution Implementation

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.

Adding the Serde Imports to the Classpath

Serializing Results

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

@Test
void serializeSuccessfulResult(ObjectMapper objectMapper)
    throws IOException {
  // Given
  ApiOperation op = new ApiOperation("clean", success("All good"));
  // When
  String json = objectMapper.writeValueAsString(op);
  // Then
  assertEquals("""
      {"name":"clean","result":{"success":"All good"}}""", json);
}

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

{
  "name": "clean",
  "result": {
    "failure": null,
    "success": "All good"
  }
}

Next, we can try serializing a failed result.

@Test
void serializeFailedResult(ObjectMapper objectMapper)
    throws IOException {
  // Given
  ApiOperation op = new ApiOperation("build", failure("Oops"));
  // When
  String json = objectMapper.writeValueAsString(op);
  // Then
  assertEquals("""
      {"name":"build","result":{"failure":"Oops"}}""", json);
}

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

{
  "name": "build",
  "result": {
    "failure": "Oops",
    "success": null
  }
}

Deserializing Results

@Test
void deserializeSuccessfulResult(ObjectMapper objectMapper)
    throws IOException {
  // Given
  String json = """
      {"name":"check","result":{"success":"Yay"}}""";
  // When
  ApiOperation response = objectMapper.readValue(json, ApiOperation.class);
  // Then
  assertEquals("check", response.name());
  assertEquals("Yay", response.result().orElse(null));
}

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.

@Test
void deserializeFailedResult(ObjectMapper objectMapper)
    throws IOException {
  // Given
  String json = """
      {"name":"start","result":{"failure":"Nay"}}""";
  // When
  ApiOperation response = objectMapper.readValue(json, ApiOperation.class);
  // Then
  assertEquals("start", response.name());
  assertEquals("Nay", response.result().getFailure().orElse(null));
}