Advanced Features of the Client API

This section describes some of the advanced features of the JAX-RS Client API.

The following topics are addressed here:

Configuring the Client Request
Asynchronous Invocations in the Client API

Configuring the Client Request

Additional configuration options may be added to the client request after it is created but before it is invoked.

The following topics are addressed here:

Setting Message Headers in the Client Request
Setting Cookies in the Client Request
Adding Filters to the Client

Setting Message Headers in the Client Request

You can set HTTP headers on the request by calling the Invocation.Builder.header method.

Client client = ClientBuilder.newClient();
WebTarget myResource = client.target("http://example.com/webapi/read");
String response = myResource.request(MediaType.TEXT_PLAIN)
        .header("myHeader", "The header value")
        .get(String.class);

If you need to set multiple headers on the request, call the Invocation.Builder.headers method and pass in a javax.ws.rs.core.MultivaluedMap instance with the name-value pairs of the HTTP headers. Calling the headers method replaces all the existing headers with the headers supplied in the MultivaluedMap instance.

Client client = ClientBuilder.newClient();
WebTarget myResource = client.target("http://example.com/webapi/read");
MultivaluedMap<String, Object> myHeaders =
    new MultivaluedMap<>("myHeader", "The header value");
myHeaders.add(...);
String response = myResource.request(MediaType.TEXT_PLAIN)
        .headers(myHeaders)
        .get(String.class);

The MultivaluedMap interface allows you to specify multiple values for a given key.

MultivaluedMap<String, Object> myHeaders =
    new MultivaluedMap<String, Object>();
List<String> values = new ArrayList<>();
values.add(...)
myHeaders.add("myHeader", values

Setting Cookies in the Client Request

You can add HTTP cookies to the request by calling the Invocation.Builder.cookie method, which takes a name-value pair as parameters.

Client client = ClientBuilder.newClient();
WebTarget myResource = client.target("http://example.com/webapi/read");
String response = myResource.request(MediaType.TEXT_PLAIN)
        .cookie("myCookie", "The cookie value")
        .get(String.class);

The javax.ws.rs.core.Cookie class encapsulates the attributes of an HTTP cookie, including the name, value, path, domain, and RFC specification version of the cookie. In the following example, the Cookie object is configured with a name-value pair, a path, and a domain.

Client client = ClientBuilder.newClient();
WebTarget myResource = client.target("http://example.com/webapi/read");
Cookie myCookie = new Cookie("myCookie", "The cookie value",
    "/webapi/read", "example.com");
String response = myResource.request(MediaType.TEXT_PLAIN)
        .cookie(myCookie)
        .get(String.class);

Adding Filters to the Client

You can register custom filters with the client request or the response received from the target resource. To register filter classes when the Client instance is created, call the Client.register method.

Client client = ClientBuilder.newClient().register(MyLoggingFilter.class);

In the preceding example, all invocations that use this Client instance have the MyLoggingFilter filter registered with them.

You can also register the filter classes on the target by calling WebTarget.register.

Client client = ClientBuilder.newClient().register(MyLoggingFilter.class);
WebTarget target = client.target("http://example.com/webapi/secure")
        .register(MyAuthenticationFilter.class);

In the preceding example, both the MyLoggingFilter and MyAuthenticationFilter filters are attached to the invocation.

Request and response filter classes implement the javax.ws.rs.client.ClientRequestFilter and javax.ws.rs.client.ClientResponseFilter interfaces, respectively. Both of these interfaces define a single method, filter. All filters must be annotated with javax.ws.rs.ext.Provider.

The following class is a logging filter for both client requests and client responses.

@Provider
public class MyLoggingFilter implements ClientRequestFilter,
        ClientResponseFilter {
    static final Logger logger = Logger.getLogger(...);

    // implement the ClientRequestFilter.filter method
    @Override
    public void filter(ClientRequestContext requestContext)
            throws IOException {
        logger.log(...);
        ...
    }

    // implement the ClientResponseFilter.filter method
    @Override
    public void filter(ClientRequestContext requestContext,
           ClientResponseContext responseContext) throws IOException {
        logger.log(...);
        ...
    }
}

If the invocation must be stopped while the filter is active, call the context object’s abortWith method, and pass in a javax.ws.rs.core.Response instance from within the filter.

@Override
public void filter(ClientRequestContext requestContext) throws IOException {
    ...
    Response response = new Response();
    response.status(500);
    requestContext.abortWith(response);
}

Asynchronous Invocations in the Client API

In networked applications, network issues can affect the perceived performance of the application, particularly in long-running or complicated network calls. Asynchronous processing helps prevent blocking and makes better use of an application’s resources.

In the JAX-RS Client API, the Invocation.Builder.async method is used when constructing a client request to indicate that the call to the service should be performed asynchronously. An asynchronous invocation returns control to the caller immediately, with a return type of java.util.concurrent.Future<T> (part of the Java SE concurrency API) and with the type set to the return type of the service call. Future<T> objects have methods to check if the asynchronous call has been completed, to retrieve the final result, to cancel the invocation, and to check if the invocation has been cancelled.

The following example shows how to invoke an asynchronous request on a resource.

Client client = ClientBuilder.newClient();
WebTarget myResource = client.target("http://example.com/webapi/read");
Future<String> response = myResource.request(MediaType.TEXT_PLAIN)
        .async()
        .get(String.class);

Using Custom Callbacks in Asynchronous Invocations

The InvocationCallback interface defines two methods, completed and failed, that are called when an asynchronous invocation either completes successfully or fails, respectively. You may register an InvocationCallback instance on your request by creating a new instance when specifying the request method.

The following example shows how to register a callback object on an asynchronous invocation.

Client client = ClientBuilder.newClient();
WebTarget myResource = client.target("http://example.com/webapi/read");
Future<Customer> fCustomer = myResource.request(MediaType.TEXT_PLAIN)
        .async()
        .get(new InvocationCallback<Customer>() {
            @Override
            public void completed(Customer customer) {
            // Do something with the customer object
            }
            @Override
             public void failed(Throwable throwable) {
            // handle the error
            }
    });

Using Reactive Approach in Asynchronous Invocations

Using custom callbacks in asynchronous invocations is easy in simple cases and when there are many independent calls to make. In nested calls, using custom callbacks becomes very difficult to implement, debug, and maintain.

JAX-RS defines a new type of invoker called as RxInvoker and a default implementation of this type is CompletionStageRxInvoker. The new rx method is used as in the following example:

CompletionStage<String> csf = client.target("forecast/{destination}") resolveTemplate("destination", "mars").request().rx().get(String.class);
csf.thenAccept(System.out::println);

In the example, an asynchronous processing of the interface CompletionStage<String> is created and waits till it is completed and the result is displayed. The CompletionStage that is returned can then be used only to retrieve the result as shown in the above example or can be combined with other completion stages to ease and improve the processing of asynchronous tasks.

Using Server-Sent Events

Server-sent Events (SSE) technology is used to asynchronously push notifications to the client over standard HTTP or HTTPS protocol. Clients can subscribe to event notifications that originate on a server. Server generates events and sends these events back to the clients that are subscribed to receive the notifications. The one-way communication channel connection is established by the client. Once the connection is established, the server sends events to the client whenever new data is available.

The communication channel established by the client lasts till the client closes the connection and it is also re-used by the server to send multiple events from the server.

Overview of the SSE API

The SSE API is defined in the javax.ws.rs.sse package that includes the interfaces SseEventSink, SseEvent, Sse, and SseEventSource. To accept connections and send events to one or more clients, inject an SseEventSink in the resource method that produces the media type text/event-stream.

The following example shows how to accept the SSE connections and to send events to the clients:

@GET
@Path("eventStream")
@Produces(MediaType.SERVER_SENT_EVENTS)
public void eventStream(@Context SseEventSink eventSink,
@Context Sse sse) {
executor.execute(() -> {
try (SseEventSink sink = eventSink) {
eventSink.send(sse.newEvent("event1"));
eventSink.send(sse.newEvent("event2"));
eventSink.send(sse.newEvent("event3"));
}
});
}

The SseEventsink is injected into the resource method and the underlying client connection is kept open and used to send events. The connection persists until the client disconnects from the server. The method send returns an instance of CompletionStage<T> which indicates the action of asynchronously sending a message to a client is enabled.

The events that are streamed to the clients can be defined with the details such as event, data, id, retry, and comment.

Broadcasting Using SSE

Broadcasting is the action of sending events to multiple clients simultaneously. JAX-RS SSE API provides SseBroadcaster to register all SseEventSink instances and send events to all registered event outputs. The life-cycle and scope of an SseBroadcaster is fully controlled by applications and not the JAX-RS runtime. The following example show the use of broadcasters:

@Path("/")
@Singleton
public class SseResource {
@Context
private Sse sse;
private volatile SseBroadcaster sseBroadcaster;
@PostConstruct
public init() {
this.sseBroadcaster = sse.newBroadcaster();
}

@GET
@Path("register")
@Produces(MediaType.SERVER_SENT_EVENTS)
public void register(@Context SseEventSink eventSink) {
eventSink.send(sse.newEvent("welcome!"));
sseBroadcaster.register(eventSink);
}

@POST
@Path("broadcast")
@Consumes(MediaType.MULTIPART_FORM_DATA)
public void broadcast(@FormParam("event") String event) {
sseBroadcaster.broadcast(sse.newEvent(event));
}
}

@Singleton annotation is defined for the resource class restricting the creation of multiple instances of the class. The register method on a broadcaster is used to add a new SseEventSink; the broadcast method is used to send an SSE event to all registered clients.

Listening and Receiving Events

JAX-RS SSE provides the SseEventSource interface for the client to subscribe to notifications. The client can get asynchronously notified about incoming events by invoking one of the subscribe methods in javax.ws.rs.sse.SseEventSource.

The following example shows how to use the SseEventSource API to open an SSE connection and read some of the messages for a period:

WebTarget target = client.target("http://...");
try (SseEventSource source = SseEventSource.target(target).build()) {
source.register(System.out::println);
source.open();
Thread.sleep(500); // Consume events for just 500 ms
source.close();
} catch (InterruptedException e) {
// falls through
}