Guide to Try in Vavr

1. Overview

In this article, we’ll look at a functional way of error handling other than a standard try-catch block.

We’ll be using Try class from Vavr library that will allow us to create more fluent and conscious API by embedding error handling into normal program processing flow.

If you want to get more information about Vavr, check this article.

2. Standard Way of Handling Exceptions

Let’s say that we have a simple interface with a method call() that returns a Response or throws ClientException that is a checked exception in a case of a failure:

public interface HttpClient {
    Response call() throws ClientException;
}

The Response is a simple class with only one id field:

public class Response {
    public final String id;

    public Response(String id) {
        this.id = id;
    }
}

Let’s say that we have a service that calls that HttpClient, then we need to handle that checked exception in a standard try-catch block:

public Response getResponse() {
    try {
        return httpClient.call();
    } catch (ClientException e) {
        return null;
    }
}

When we want to create API that is fluent and is written functionally, each method that throws checked exceptions disrupts program flow, and our program code consists of many try-catch blocks making it very hard to read.

Ideally, we will want to have a special class that encapsulates result state ( success or a failure ), and then we can chain operations according to that result.

3. Handling Exceptions With Try

Vavr library gives us a special container that represents a computation that may either result in an exception or complete successfully.

Enclosing operation within Try object gave us a result that is either Success or a Failure. Then we can execute further operations accordingly to that type.

Let’s look how the same method getResponse() as in a previous example will look like using Try:

public class VavrTry {
    private HttpClient httpClient;

    public Try<Response> getResponse() {
        return Try.of(httpClient::call);
    }

    // standard constructors
}

The important thing to notice is a return type Try<Response>. When a method returns such result type, we need to handle that properly and keep in mind, that result type can be Success or Failure, so we need to handle that explicitly at a compile time.

3.1. Handling Success

Let’s write a test case that is using our Vavr class in a case when httpClient is returning a successful result. The method getResponse() returns Try<Resposne> object. Therefore we can call map() method on it that will execute an action on Response only when Try will be of Success type:

@Test
public void givenHttpClient_whenMakeACall_shouldReturnSuccess() {
    // given
    Integer defaultChainedResult = 1;
    String id = "a";
    HttpClient httpClient = () -> new Response(id);

    // when
    Try<Response> response = new VavrTry(httpClient).getResponse();
    Integer chainedResult = response
      .map(this::actionThatTakesResponse)
      .getOrElse(defaultChainedResult);
    Stream<String> stream = response.toStream().map(it -> it.id);

    // then
    assertTrue(!stream.isEmpty());
    assertTrue(response.isSuccess());
    response.onSuccess(r -> assertEquals(id, r.id));
    response.andThen(r -> assertEquals(id, r.id)); 
 
    assertNotEquals(defaultChainedResult, chainedResult);
}

Function actionThatTakesResponse() simply takes Response as an argument and returns hashCode of an id field:

public int actionThatTakesResponse(Response response) {
    return response.id.hashCode();
}

Once we map our value using actionThatTakesResponse() function we execute method getOrElse().

If Try has a Success inside it, it returns value of Try, otherwise, it returns defaultChainedResult. Our httpClient execution was successful thus the isSuccess method returns true. Then we can execute onSuccess() method that makes an action on a Response object. Try has also a method andThen that takes a Consumer that consume a value of a Try when that value is a Success.

We can treat our Try response as a stream. To do so we need to convert it to a Stream using toStream() method, then all operations that are available in Stream class could be used to make operations on that result.

If we want to execute an action on Try type, we can use transform() method that takes Try as an argument and make an action on it without unwrapping enclosed value:

public int actionThatTakesTryResponse(Try<Response> response, int defaultTransformation){
    return response.transform(responses -> response.map(it -> it.id.hashCode())
      .getOrElse(defaultTransformation));
}

3.2. Handling Failure

Let’s write an example when our HttpClient will throw ClientException when executed.

Comparing to the previous example, our getOrElse method will return defaultChainedResult because Try will be of a Failure type:

@Test
public void givenHttpClientFailure_whenMakeACall_shouldReturnFailure() {
    // given
    Integer defaultChainedResult = 1;
    HttpClient httpClient = () -> {
        throw new ClientException("problem");
    };

    // when
    Try<Response> response = new VavrTry(httpClient).getResponse();
    Integer chainedResult = response
        .map(this::actionThatTakesResponse)
        .getOrElse(defaultChainedResult);
     Option<Response> optionalResponse = response.toOption();

    // then
    assertTrue(optionalResponse.isEmpty());
    assertTrue(response.isFailure());
    response.onFailure(ex -> assertTrue(ex instanceof ClientException));
    assertEquals(defaultChainedResult, chainedResult);
}

The method getReposnse() returns Failure thus method isFailure returns true.

We could execute the onFailure() callback on returned response and see that exception is of ClientException type. The object that is of a Try type could be mapped to Option type using toOption() method.

It is useful when we do not want to carry our Try result throughout all codebase, but we have methods that are handling an explicit absence of value using Option type. When we map our Failure to Option, then method isEmpty() is returning true. When Try object is a type Success calling toOption on it will make Option that is defined thus method isDefined() will return true.

3.3. Utilizing Pattern Matching

When our httpClient returns an Exception, we could do a pattern matching on a type of that Exception. Then according to a type of that Exception in recover() a method we can decide if we want to recover from that exception and turn our Failure into Success or if we want to leave our computation result as a Failure:

@Test
public void givenHttpClientThatFailure_whenMakeACall_shouldReturnFailureAndNotRecover() {
    // given
    Response defaultResponse = new Response("b");
    HttpClient httpClient = () -> {
        throw new RuntimeException("critical problem");
    };

    // when
    Try<Response> recovered = new VavrTry(httpClient).getResponse()
      .recover(r -> Match(r).of(
          Case(instanceOf(ClientException.class), defaultResponse)
      ));

    // then
    assertTrue(recovered.isFailure());

Pattern matching inside the recover() method will turn Failure into Success only if a type of an Exception is a ClientException. Otherwise, it will leave it as a Failure(). We see that our httpClient is throwing RuntimeException thus our recovery method will not handle that case, therefore isFailure() returns true.

If we want to get the result from recovered object, but in a case of critical failure rethrows that exception we can do it using getOrElseThrow() method:

recovered.getOrElseThrow(throwable -> {
    throw new RuntimeException(throwable);
});

Some errors are critical, and when they occur, we want to signal that explicitly by throwing the exception higher in a call stack, to let the caller decide about further exception handling. In such cases, rethrowing exception like in above example is very useful.

When our client throws a non-critical exception, our pattern matching in a recover() method will turn our Failure into Success. We are recovering from two types of exceptions ClientException and IllegalArgumentException:

@Test
public void givenHttpClientThatFailure_whenMakeACall_shouldReturnFailureAndRecover() {
    // given
    Response defaultResponse = new Response("b");
    HttpClient httpClient = () -> {
        throw new ClientException("non critical problem");
    };

    // when
    Try<Response> recovered = new VavrTry(httpClient).getResponse()
      .recover(r -> Match(r).of(
        Case(instanceOf(ClientException.class), defaultResponse),
        Case(instanceOf(IllegalArgumentException.class), defaultResponse)
       ));
    
    // then
    assertTrue(recovered.isSuccess());
}

We see that isSuccess() returns true, so our recovery handling code worked successfully.

4. Conclusion

This article shows a practical use of Try container from Vavr library. We looked at the practical examples of using that construct by handling failure in the more functional way. Using Try will allow us to create more functional and readable API.