January 17, 2015

Reactive Jersey Client using Java 8, RxJava and Netflix Hystrix

In this post I will show you how to use Jersey Client Reactive API, it's RxJava Observable support together with Netflix Hystrix, latency and fault tolerance library. All sources are placed in GitHub jersey--examples--rx-client-java8-webapp project.

Jersey framework contains Reactive Client API. Reactive Jersey Client API is a generic API allowing end users to utilize the popular reactive programming model when using Jersey Client. Reactive programming is very popular these days. It helps you to implement asynchronous code with solved callback hell issue.


Jersey supports RxJava ObservableJava 8 CompletionStage and CompletableFutureGuava ListenableFuture and FuturesJSR-166e CompletableFuture. It also provides SPI to be extended by custom reactive libraries.

There is excellent 3 part blog post series written by Michal Gajdoš about Reactive Jersey Client:
  1. Reactive Jersey Client – Motivation
  2. Reactive Jersey Client – Usage and Supported Reactive Libraries
  3. Reactive Jersey Client – Customization (SPI)

Jersey source code contains also examples for supported reactive libraries, see modules:


Hystrix is a latency and fault tolerance library designed to isolate points of access to remote systems, services and 3rd party libraries, stop cascading failure and enable resilience in complex distributed systems where failure is inevitable.

You usually use Hystrix to isolate dependent system call into HystrixCommand class. It allows to be executed synchronously, asynchronously (returns java.util.concurrent.Future) and also asynchronously via RxJava Observable.


In case dependent system already supports RxJava Observable API you can use specific HystrixObservableCommand class. And thanks to Jersey Reactive Client API and its RxJava support it allows us to write resilient JAX-RS client code.

private class ForecastCommand extends HystrixObservableCommand<Forecast> {
    private final Destination destination;
    protected Observable<Forecast> run() {
        return RxObservable.from(forecastWebTarget)
                .resolveTemplate("destination", destination.getDestination())
    protected Observable<Forecast> getFallback() {
        return Observable.just(new Forecast(destination.getDestination(), "N/A"));

The code above creates new Hystrix RxJava Observable ready Command that invokes remote REST API using Jersey Reactive Client API. Whenever API call fails or times out a getFallback() method is invoked. And in this case we return Forecast instance with N/A forecast value.

Whole example web application enhanced by code using Hystrix is placed into my GitHub jersey--examples--rx-client-java8-webapp repository. Shown and little but simplified code snipped is from HystrixObservableAgentResource class. The example module is clone of rx-client-java8-webapp.

To run the example:
    mvn clean package jetty:run

At beginning of HystrixObservableAgentResource class there are TIMEOUT_* constants. You can play with values and you will see that sometimes you don't get all domain objects' values and sometimes you see default values (N/A for Forecast and -1 for Calculation). You can also play with Thread.sleep intervals but because of Hystrix timeout support the overall JAX-RS resource method processing time is never (too much) longer than TIMEOUT_OVERALL (currently 900 ms).

You can also check unit test RxClientsTest. Processing time is expected between 850 and 950 ms!