JBoss.orgCommunity Documentation

Chapter 27. JAX-RS 2.1 Additions

27.1. CompletionStage support
27.2. Reactive Clients API
27.3. Server-Sent Events (SSE)
27.3.1. SSE Server
27.3.2. SSE Broadcasting
27.3.3. SSE Client
27.4. Java API for JSON Binding

JAX-RS 2.1 adds more asynchronous processing support in both the Client and the Server API. The specification adds a Reactive programming style to the Client side and Server-Sent Events (SSE) protocol support to both client and server.

The specification adds support for declaring asynchronous resource methods by returning a CompletionStage instead of using the @Suspended annotation.

The specification defines a new type of invoker named RxInvoker, and a default implementation of this type named CompletionStageRxInvoker. CompletionStageRxInvoker implements Java 8's interface CompletionStage. This interface declares a large number of methods dedicated to managing asynchronous computations.

There is also a new rx method which is used in a similar manner to async.

SSE is part of HTML standard, currently supported by many browsers. It is a server push technology, which provides a way to establish a one-way channel to continuously send data to clients. SSE events are pushed to the client via a long-running HTTP connection. In case of lost connection, clients can retrieve missed events by setting a "Last-Event-ID" HTTP header in a new request.

SSE stream has text/event-stream media type and contains multiple SSE events. SSE event is a data structure encoded with UTF-8 and contains fields and comment. The field can be event, data, id, retry and other kinds of field will be ignored.

From JAX-RS 2.1, Server-sent Events APIs are introduced to support sending, receiving and broadcasting SSE events.

RESTEasy supports both JSON-B and JSON-P. In accordance with the specification, entity providers for JSON-B take precedence over those for JSON-P for all types except JsonValue and its sub-types.

The support for JSON-B is provided by the JsonBindingProvider from resteasy-json-binding-provider module. To satisfy JAX-RS 2.1 requirements, JsonBindingProvider takes precedence over the other providers for dealing with JSON payloads, in particular the Jackson one. The JSON outputs (for the same input) from Jackson and JSON-B reference implementation can be slightly different. As a consequence, in order to allow retaining backward compatibility, RESTEasy offers a resteasy.preferJacksonOverJsonB context property that can be set to true to disable JsonBindingProvider for the current deloyment.

WildFly 14 supports specifying the default value for the resteasy.preferJacksonOverJsonB context property by setting a system property with the same name. Moreover, if no value is set for the context and system properties, it scans JAX-RS deployments for Jackson annotations and sets the property to true if any of those annotations is found.