Chapter 37. Reactive programming support

37.1. Plugable reactive types
37.2. Behavior of reactive types

JAX-RS 2.1 adds support for returning the asynchronous reactive type CompletableFuture, but RESTEasy supports much more than this, when it comes to asynchronous programming.

37.1. Plugable reactive types

Out of the box, RESTEasy supports CompletableFuture for single events, and org.reactivestreams.Publisher (from Reactive Streams) for multiple events.

The optional modules resteasy-rxjava and resteasy-rxjava2 add support for the RxJava 1 and 2 reactive types, such as Single and Observable, which means if you import this dependency you can just start returning reactive types from those frameworks from your resource methods.

Adding support for other reactive types can be done by declaring a @Provider for the interfaces AsyncStreamProvider (for streams) and AsyncResponseProvider (for single values), which both have a single method to convert the new reactive type into (respectively) a Publisher (for streams) or a CompletionStage (for single values).

37.2. Behavior of reactive types

Single-value reactive types behave like the specification of JAX-RS 2.1 wrt. CompletionStage, which is that the reactive value will be subscribed to, the request will be turned asynchronous, and only resumed when the reactive value is resolved to either a value (normal completion), or an exception.

Multiple-value reactive types (streams) behave in three possible ways, depending on how the resource method is annotated:

Default case (no special annotation): Collect every value until the stream is complete, then wrap into a java.util.List entity and send to the client.
@Produces(MediaType.SERVER_SENT_EVENTS)