Chapter 5. Client API

Refer to the dependencies for details on the dependencies when using the Jersey JAX-RS Client support.

You may also want to use a custom Connector implementation. In such case you would need to include additional dependencies on the module(s) containing the custom client connector that you want to use. See section "Configuring custom Connectors" about how to use and configure a custom Jersey client transport Connector.

JAX-RS Client API is designed to allow fluent programming model. This means, a construction of a Client instance, from which a WebTarget is created, from which a request Invocation is built and invoked can be chained in a single "flow" of invocations. The individual steps of the flow will be shown in the following sections. To utilize the client API it is first necessary to build an instance of a Client using one of the static ClientBuilder factory methods. Here's the most simple example:

Client client = ClientBuilder.newClient();

The ClientBuilder is a JAX-RS API used to create new instances of Client. In a slightly more advanced scenarios, ClientBuilder can be used to configure additional client instance properties, such as a SSL transport settings, if needed (see ??? below).

A Client instance can be configured during creation by passing a ClientConfig to the newClient(Configurable) ClientBuilder factory method. ClientConfig implements Configurable and therefore it offers methods to register providers (e.g. features or individual entity providers, filters or interceptors) and setup properties. The following code shows a registration of custom client filters:

ClientConfig clientConfig = new ClientConfig();
clientConfig.register(MyClientResponseFilter.class);
clientConfig.register(new AnotherClientFilter());
Client client = ClientBuilder.newClient(clientConfig);

In the example, filters are registered using the ClientConfig.register(...) method. There are multiple overloaded versions of the method that support registration of feature and provider classes or instances. Once a ClientConfig instance is configured, it can be passed to the ClientBuilder to create a pre-configured Client instance.

Note that the Jersey ClientConfig supports the fluent API model of Configurable. With that the code that configures a new client instance can be also written using a more compact style as shown below.

Client client = ClientBuilder.newClient(new ClientConfig()
        .register(MyClientResponseFilter.class)
        .register(new AnotherClientFilter());

The ability to leverage this compact pattern is inherent to all JAX-RS and Jersey Client API components.

Since Client implements Configurable interface too, it can be configured further even after it has been created. Important is to mention that any configuration change done on a Client instance will not influence the ClientConfig instance that was used to provide the initial Client instance configuration at the instance creation time. The next piece of code shows a configuration of an existing Client instance.

client.register(ThirdClientFilter.class);

Similarly to earlier examples, since Client.register(...) method supports the fluent API style, multiple client instance configuration calls can be chained:

client.register(FilterA.class)
      .register(new FilterB())
      .property("my-property", true);

To get the current configuration of the Client instance a getConfiguration() method can be used.

ClientConfig clientConfig = new ClientConfig();
clientConfig.register(MyClientResponseFilter.class);
clientConfig.register(new AnotherClientFilter());
Client client = ClientBuilder.newClient(clientConfig);
client.register(ThirdClientFilter.class);
Configuration newConfiguration = client.getConfiguration();

In the code, an additional MyClientResponseFilter class and AnotherClientFilter instance are registered in the clientConfig. The clientConfig is then used to construct a new Client instance. The ThirdClientFilter is added separately to the constructed Client instance. This does not influence the configuration represented by the original clientConfig. In the last step a newConfiguration is retrieved from the client. This configuration contains all three registered filters while the original clientConfig instance still contains only two filters. Unlike clientConfig created separately, the newConfiguration retrieved from the client instance represents a live client configuration view. Any additional configuration changes made to the client instance are also reflected in the newConfiguration. So, newConfiguration is really a view of the client configuration and not a configuration state copy. These principles are important in the client API and will be used in the following sections too. For example, you can construct a common base configuration for all clients (in our case it would be clientConfig) and then reuse this common configuration instance to configure multiple client instances that can be further specialized. Similarly, you can use an existing client instance configuration to configure another client instance without having to worry about any side effects in the original client instance.

Once you have a Client instance you can create a WebTarget from it.

WebTarget webTarget = client.target("http://example.com/rest");

A Client contains several target(...) methods that allow for creation of WebTarget instance. In this case we're using target(String uri) version. The uri passed to the method as a String is the URI of the targeted web resource. In more complex scenarios it could be the context root URI of the whole RESTful application, from which WebTarget instances representing individual resource targets can be derived and individually configured. This is possible, because JAX-RS WebTarget also implements Configurable:

WebTarget webTarget = client.target("http://example.com/rest");
webTarget.register(FilterForExampleCom.class);

The configuration principles used in JAX-RS client API apply to WebTarget as well. Each WebTarget instance inherits a configuration from its parent (either a client or another web target) and can be further custom-configured without affecting the configuration of the parent component. In this case, the FilterForExampleCom will be registered only in the webTarget and not in client. So, the client can still be used to create new WebTarget instances pointing at other URIs using just the common client configuration, which FilterForExampleCom filter is not part of.

Let's assume we have a webTarget pointing at "http://example.com/rest" URI that represents a context root of a RESTful application and there is a resource exposed on the URI "http://example.com/rest/resource". As already mentioned, a WebTarget instance can be used to derive other web targets. Use the following code to define a path to the resource.

WebTarget resourceWebTarget = webTarget.path("resource");

The resourceWebTarget now points to the resource on URI "http://example.com/rest/resource". Again if we configure the resourceWebTarget with a filter specific to the resource, it will not influence the original webTarget instance. However, the filter FilterForExampleCom registration will still be inherited by the resourceWebTarget as it has been created from webTarget. This mechanism allows you to share the common configuration of related resources (typically hosted under the same URI root, in our case represented by the webTarget instance), while allowing for further configuration specialization based on the specific requirements of each individual resource. The same configuration principles of inheritance (to allow common config propagation) and decoupling (to allow individual config customization) applies to all components in JAX-RS Client API discussed below.

Let's say there is a sub resource on the path "http://example.com/rest/resource/helloworld". You can derive a WebTarget for this resource simply by:

WebTarget helloworldWebTarget = resourceWebTarget.path("helloworld");

Let's assume that the helloworld resource accepts a query param for GET requests which defines the greeting message. The next code snippet shows a code that creates a new WebTarget with the query param defined.

WebTarget helloworldWebTargetWithQueryParam =
        helloworldWebTarget.queryParam("greeting", "Hi World!");

Please note that apart from methods that can derive new WebTarget instance based on a URI path or query parameters, the JAX-RS WebTarget API contains also methods for working with matrix parameters too.

Let's now focus on invoking a GET HTTP request on the created web targets. To start building a new HTTP request invocation, we need to create a new Invocation.Builder.

Invocation.Builder invocationBuilder =
        helloworldWebTargetWithQueryParam.request(MediaType.TEXT_PLAIN_TYPE);
invocationBuilder.header("some-header", "true");

A new invocation builder instance is created using one of the request(...) methods that are available on WebTarget. A couple of these methods accept parameters that let you define the media type of the representation requested to be returned from the resource. Here we are saying that we request a "text/plain" type. This tells Jersey to add a Accept: text/plain HTTP header to our request.

The invocationBuilder is used to setup request specific parameters. Here we can setup headers for the request or for example cookie parameters. In our example we set up a "some-header" header to value true.

Once finished with request customizations, it's time to invoke the request. We have two options now. We can use the Invocation.Builder to build a generic Invocation instance that will be invoked some time later. Using Invocation we will be able to e.g. set additional request properties which are properties in a batch of several requests and use the generic JAX-RS Invocation API to invoke the batch of requests without actually knowing all the details (such as request HTTP method, configuration etc.). Any properties set on an invocation instance can be read during the request processing. For example, in a custom ClientRequestFilter you can call getProperty() method on the supplied ClientRequestContext to read a request property. Note that these request properties are different from the configuration properties set on Configurable. As mentioned earlier, an Invocation instance provides generic invocation API to invoke the HTTP request it represents either synchronously or asynchronously. See the Chapter 11, Asynchronous Services and Clients for more information on asynchronous invocations.

In case you do not want to do any batch processing on your HTTP request invocations prior to invoking them, there is another, more convenient approach that you can use to invoke your requests directly from an Invocation.Builder instance. This approach is demonstrated in the next Java code listing.

Response response = invocationBuilder.get();

While short, the code in the example performs multiple actions. First, it will build the the request from the invocationBuilder. The URI of request will be http://example.com/rest/resource/helloworld?greeting="Hi%20World!" and the request will contain some-header: true and Accept: text/plain headers. The request will then pass trough all configured request filters ( AnotherClientFilter, ThirdClientFilter and FilterForExampleCom). Once processed by the filters, the request will be sent to the remote resource. Let's say the resource then returns an HTTP 200 message with a plain text response content that contains the value sent in the request greeting query parameter. Now we can observe the returned response:

System.out.println(response.getStatus());
System.out.println(response.readEntity(String.class));

which will produce the following output to the console:

200
Hi World!

As we can see, the request was successfully processed (code 200) and returned an entity (representation) is "Hi World!". Note that since we have configured a MyClientResponseFilter in the resource target, when response.readEntity(String.class) gets called, the response returned from the remote endpoint is passed through the response filter chain (including the MyClientResponseFilter) and entity interceptor chain and at last a proper MessageBodyReader<T> is located to read the response content bytes from the response stream into a Java String instance. Check Chapter 10, Filters and Interceptors to lear more about request and response filters and entity interceptors.

Imagine now that you would like to invoke a POST request but without any query parameters. You would just use the helloworldWebTarget instance created earlier and call the post() instead of get().

Response postResponse =
        helloworldWebTarget.request(MediaType.TEXT_PLAIN_TYPE)
                .post(Entity.entity("A string entity to be POSTed", MediaType.TEXT_PLAIN));

The following code puts together the pieces used in the earlier examples.

ClientConfig clientConfig = new ClientConfig();
clientConfig.register(MyClientResponseFilter.class);
clientConfig.register(new AnotherClientFilter());

Client client = ClientBuilder.newClient(clientConfig);
client.register(ThirdClientFilter.class);

WebTarget webTarget = client.target("http://example.com/rest");
webTarget.register(FilterForExampleCom.class);
WebTarget resourceWebTarget = webTarget.path("resource");
WebTarget helloworldWebTarget = resourceWebTarget.path("helloworld");
WebTarget helloworldWebTargetWithQueryParam =
        helloworldWebTarget.queryParam("greeting", "Hi World!");

Invocation.Builder invocationBuilder =
        helloworldWebTargetWithQueryParam.request(MediaType.TEXT_PLAIN_TYPE);
invocationBuilder.header("some-header", "true");

Response response = invocationBuilder.get();
System.out.println(response.getStatus());
System.out.println(response.readEntity(String.class));

Now we can try to leverage the fluent API style to write this code in a more compact way.

Client client = ClientBuilder.newClient(new ClientConfig()
            .register(MyClientResponseFilter.class)
            .register(new AnotherClientFilter()));

String entity = client.target("http://example.com/rest")
            .register(FilterForExampleCom.class)
            .path("resource/helloworld")
            .queryParam("greeting", "Hi World!")
            .request(MediaType.TEXT_PLAIN_TYPE)
            .header("some-header", "true")
            .get(String.class);

The code above does the same thing except it skips the generic Response processing and directly requests an entity in the last get(String.class) method call. This shortcut method let's you specify that (in case the response was returned successfully with a HTTP 2xx status code) the response entity should be returned as Java String type. This compact example demonstrates another advantage of the JAX-RS client API. The fluency of JAX-RS Client API is convenient especially with simple use cases. Here is another a very simple GET request returning a String representation (entity):

String responseEntity = ClientBuilder.newClient()
            .target("http://example.com").path("resource/rest")
                        .request().get(String.class);

Some client invocations, like asynchronous or reactive, could lead to a need to start a new thread. This is being done on provided ExecutorService or ScheduledExecutorService. ClientBuilder has two methods, which can be used to define them: executorService(ExecutorService) and scheduledExecutorService(ScheduledExecutorService). When specified, all invocations which do require running on another thread, should be executed using provided services.

Default values do depend on the environment - in Java/Jakarta EE container, it has to be ManagedExecutorService and ManagedScheduledExecutorService, for Java SE it would be ForkJoinPool.commonPool for Executor service and something undefined for Scheduled executor service.

ExecutorService myExecutorService = Executors.newCachedThreadPool();
Client client = ClientBuilder.newBuilder().executorService(myExecutorService).build();

The support for new application-defined representations as Java types requires the implementation of the same JAX-RS entity provider extension interfaces as for the server side JAX-RS API, namely MessageBodyReader<T> and MessageBodyWriter<T> respectively, for request and response entities (or inbound and outbound representations).

Classes or implementations of the provider-based interfaces need to be registered as providers within the JAX-RS or Jersey Client API components that implement Configurable contract (ClientBuilder, Client, WebTarget or ClientConfig), as was shown in the earlier sections. Some media types are provided in the form of JAX-RS Feature a concept that allows the extension providers to group together multiple different extension providers and/or configuration properties in order to simplify the registration and configuration of the provided feature by the end users. For example, MoxyJsonFeature can be register to enable and configure JSON binding support via MOXy library.

The default connector is the most advanced connector, and it supports the most features Jersey has to offer. However, there are a few limitations coming from the HttpUrlConnection

One limitation is in the variety of HTTP methods supported by the HttpUrlConnection, since only the original HTTP/1.1 methods are supported. For instance, HTTP Patch method is not supported. See property HttpUrlConnector.SET_METHOD_WORKAROUND in the Appendix Section A.7, “The default HttpUrlConnector properties” for a possible workaround.

Also, in the default transport connector, there are some restrictions on the headers, that can be sent in the default configuration. HttpUrlConnectorProvider uses HttpUrlConnection as an underlying connection implementation. This JDK class by default restricts the use of following headers:

The underlying connection can be configured to permit all headers to be sent, however this behaviour can be changed only by setting the system property sun.net.http.allowRestrictedHeaders.

                        Client client = ClientBuilder.newClient();
                        System.setProperty("sun.net.http.allowRestrictedHeaders", "true");

                        Response response = client.target(yourUri).path(yourPath).request().
                        header("Origin", "http://example.com").
                        header("Access-Control-Request-Method", "POST").
                        get();
                    

The limited configurability of the HttpUrlConnection is another aspect to consider. For details, see Java Networking Properties, for instance property http.maxConnections.

For each Connector a property file defining properties tweaking the actual Connector exists. There are ClientProperties properties that apply to the default HttpUrlConnectorProvider. Many of the properties are also understood by various Connectors. Each of the ConnectorProvider defines properties that apply to it.

Moreover, each Connector supports a list of properties that are unique for the Connector. The list of the client connector properties can be found in the Appendix A, Configuration Properties.

It is not possible to provide all the settings the underlying HTTP Clients support. For Apache HTTP Client, and for Jetty HTTP Client, it is possible to access directly the HTTP Client classes and invoke setter methods there.

                        org.apache.http.client.CredentialsProvider credentialsProvider = new org.apache.http.impl.client.BasicCredentialsProvider();
                        credentialsProvider.setCredentials(
                            org.apache.http.auth.AuthScope.ANY,
                            new org.apache.http.auth.UsernamePasswordCredentials("name", "password")
                        );
                        ApacheHttpClientBuilderConfigurator apacheHttpClientBuilderConfigurator = (httpClientBuilder) -> {
                            return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
                        };

                        ClientConfig cc = new ClientConfig();
                        cc.register(apacheHttpClientBuilderConfigurator);
                        cc.connectorProvider(new ApacheConnectorProvider());
                        Client client = ClientBuilder.newClient(cc);
                        ...
                    

                        org.apache.hc.client5.http.auth.CredentialsStore credentialsProvider = new org.apache.hc.client5.http.impl.auth.BasicCredentialsProvider();
                        credentialsProvider.setCredentials(
                            new org.apache.hc.client5.http.auth.AuthScope("localhost", getPort()),
                            new org.apache.hc.client5.http.auth.UsernamePasswordCredentials("name", "password".toCharArray())
                        );
                        Apache5HttpClientBuilderConfigurator apache5HttpClientBuilderConfigurator = (httpClientBuilder) -> {
                            return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
                        };

                        ClientConfig cc = new ClientConfig();
                        cc.register(apache5HttpClientBuilderConfigurator);
                        cc.connectorProvider(new Apache5ConnectorProvider());
                        Client client = ClientBuilder.newClient(cc);
                        ...
                    

                        HttpClient httpClient = new HttpClient(...);
                        ClientConfig clientConfig = new ClientConfig()
                            .connectorProvider(new JettyConnectorProvider())
                            .register(new JettyHttpClientSupplier(httpClient));
                        Client client = ClientBuilder.newClient(clientConfig);
                        ...
                    

                        HttpClient httpClient = new HttpClient(...);
                        ClientConfig clientConfig = new ClientConfig()
                            .connectorProvider(new Jetty11ConnectorProvider())
                            .register(new Jetty11HttpClientSupplier(httpClient));
                        Client client = ClientBuilder.newClient(clientConfig);
                        ...
                    

Jersey supports Basic and Digest HTTP Authentication.

In order to enable http authentication support in Jersey client register the HttpAuthenticationFeature. This feature can provide both authentication methods, digest and basic. Feature can work in the following modes:

To initialize the feature use static methods and builder of this feature. Example of building the feature in Basic authentication mode:

HttpAuthenticationFeature feature = HttpAuthenticationFeature.basic("user", "superSecretPassword");

Example of building the feature in basic non-preemptive mode:

HttpAuthenticationFeature feature = HttpAuthenticationFeature.basicBuilder()
    .nonPreemptive().credentials("user", "superSecretPassword").build();

You can also build the feature without any default credentials:

HttpAuthenticationFeature feature = HttpAuthenticationFeature.basicBuilder().build();

In this case you need to supply username and password for each request using request properties:

Response response = client.target("http://localhost:8080/rest/homer/contact").request()
    .property(HTTP_AUTHENTICATION_BASIC_USERNAME, "homer")
    .property(HTTP_AUTHENTICATION_BASIC_PASSWORD, "p1swd745").get();

This allows you to reuse the same client for authenticating with many different credentials.

See javadoc of the HttpAuthenticationFeature for more details.

When using SSL/TLS protocols for the connection, SNIHostName is set automatically based on the host name in the HTTPS request.

There might be use-cases where the SNIHostName is required to be set for other host than the host specified in the HTTPS request. For those cases, when the HTTP header Host is set, the SNIHostName is set for the host specified in the Host header. Note that only Apache Connector, JDK Connector, Netty connector, and the default HttpUrlConnector do support this feature.

Sometimes, it may be required the SNIHostName is not set, or it differs from the HTTP Host header. In that case, the ClientProperties.SNI_HOST_NAME property can be utilized. The property sets the host name to be used for calculating the javax.net.ssl.SNIHostName. The property takes precedence over the HTTP Host header.

When the host name in the the ClientProperties.SNI_HOST_NAME property matches the HTTP request host, the SNIHostName is not set, and the HTTP Host header is not used for setting the SNIHostName. Turning the SNI off allows for Domain Fronting.

For this, PreInvocationInterceptor, the code that executes before the ClientRequestFilters are invoked, has been added to the client request chain. Jersey ensures all the interceptors are invoked with each request. The interceptor contains a single #beforeRequest method, which corresponds to ClientRequestFilter:

                /**
                * The method invoked before the request starts.
                * @param requestContext the request context shared with
                * ClientRequestFilter.
                */
                void beforeRequest(ClientRequestContext requestContext);
            

Note that only a single #abortWith is allowed in all PreInvocationInterceptors, otherwise an IllegalStateException is thrown. All the exceptions accumulated in PreInvocationInterceptors are thrown in a single Exception, available through #getSuppressed().

Similarly, ClientResponseFilter seems to be a good place where the total time of the HTTP request can be measured, but similarly to ClientRequestFilter, the response filter may not be invoked at all. For this, PostInvocationInterceptor has been introduced. Jersey runtime ensures that every PostInvocationInterceptor is called. Since an exception can occur during the HTTP request, PostInvocationInterceptor comes with two methods:

                /**
                * The method is invoked after a request when no
                * is thrown, or the Throwables are resolved
                * by previous PostInvocationInterceptor.
                *
                * @param requestContext the request context.
                * @param responseContext the response context
                * of the original Response or response context
                * defined by the new resolving Response.
                */
                void afterRequest(ClientRequestContext requestContext, ClientResponseContext responseContext);

                /**
                * The method is invoked after a Throwable is caught
                * during the client request chain processing.
                *
                * @param requestContext the request context.
                * @param exceptionContext the context available to handle the
                * caught Throwables.
                */
                void onException(ClientRequestContext requestContext, ExceptionContext exceptionContext);
            

The #afterRequest method is executed when no exception has been thrown during the HTTP request, #onException method is executed if the exception has been thrown during the request. It is possible to set a response in #onException, and the consecutive PostInvocationInterceptor will execute its #afterRequest method. The measuring example can looks as follows, then:

                String response = ClientBuilder.newClient().target("path")
                    .register(new PreInvocationInterceptor() {
                        @Override
                        public void beforeRequest(ClientRequestContext requestContext) {
                            startTime = System.currentTimeMillis();
                        }
                    })
                    .register(new PostInvocationInterceptor() {
                        @Override
                        public void afterRequest(ClientRequestContext requestContext, ClientResponseContext responseContext) {
                            logDuration(System.currentTimeMillis() - startTime);
                        }
                        @Override
                        public void onException(ClientRequestContext requestContext, ExceptionContext exceptionContext) {
                            logDuration(System.currentTimeMillis() - startTime);
                        }
                    })
                    .request().get().readEntity(String.class);