1. simplicity, the architecture is easier to understand and maintain; and

2. evolvability or loose coupling, clients and services can evolve over time perhaps in new and unexpected ways, while retaining backwards compatibility.

1. every resource is identified by a URI;

2. a client interacts with the resource via HTTP requests and responses using a fixed set of HTTP methods;

3. one or more representations can be returned and are identified by media types; and

4. the contents of which can link to further resources.

1. URI building usingUriBuilder andUriTemplate to safely build URIs;

2. Built-in support for Java types of representations such asbyte[],String,Number,Boolean,Character,InputStream,java.io.Reader,File,DataSource, JAXB beans as well as additional Jersey-specific JSON andMulti Part support.

3. Using the fluent builder-style API pattern to make it easier to construct requests.

Example 5.1. POST request with form parameters

Client client = ClientBuilder.newClient();WebTarget target = client.target("http://localhost:9998").path("resource");Form form = new Form();form.param("x", "foo");form.param("y", "bar");MyJAXBBean bean =target.request(MediaType.APPLICATION_JSON_TYPE)    .post(Entity.entity(form,MediaType.APPLICATION_FORM_URLENCODED_TYPE),        MyJAXBBean.class);

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

You may also want to use a customConnector 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 transportConnector.

JAX-RS Client API is designed to allow fluent programming model. This means, a construction of aClient instance, from which aWebTarget is created, from which a requestInvocation 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 aClient using one of the staticClientBuilder factory methods. Here's the most simple example:

Client client = ClientBuilder.newClient();

TheClientBuilder is a JAX-RS API used to create new instances ofClient. 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).

AClient instance can be configured during creation by passing aClientConfig to thenewClient(Configurable)ClientBuilder factory method.ClientConfig implementsConfigurable 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 theClientConfig.register(...) method. There are multiple overloaded versions of the method that support registration of feature and provider classes or instances. Once aClientConfig instance is configured, it can be passed to theClientBuilder to create a pre-configuredClient instance.

Note that the JerseyClientConfig supports the fluent API model ofConfigurable. 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.

SinceClient implementsConfigurable interface too, it can be configured further even after it has been created. Important is to mention that any configuration change done on aClient instance will not influence theClientConfig instance that was used to provide the initialClient instance configuration at the instance creation time. The next piece of code shows a configuration of an existingClient instance.

client.register(ThirdClientFilter.class);

Similarly to earlier examples, sinceClient.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 theClient instance agetConfiguration() 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 additionalMyClientResponseFilter class andAnotherClientFilter instance are registered in theclientConfig. TheclientConfig is then used to construct a newClient instance. TheThirdClientFilter is added separately to the constructedClient instance. This does not influence the configuration represented by the originalclientConfig. In the last step anewConfiguration is retrieved from theclient. This configuration contains all three registered filters while the originalclientConfig instance still contains only two filters. UnlikeclientConfig created separately, thenewConfiguration retrieved from theclient instance represents a live client configuration view. Any additional configuration changes made to theclient instance are also reflected in thenewConfiguration. So,newConfiguration is really a view of theclient 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 beclientConfig) and then reuse this common configuration instance to configure multipleclient instances that can be further specialized. Similarly, you can use an existingclient instance configuration to configure another client instance without having to worry about any side effects in the originalclient instance.

Once you have aClient instance you can create aWebTarget from it.

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

AClient contains severaltarget(...) methods that allow for creation ofWebTarget instance. In this case we're usingtarget(String uri) version. Theuri passed to the method as aString 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 whichWebTarget instances representing individual resource targets can be derived and individually configured. This is possible, because JAX-RSWebTarget also implementsConfigurable:

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

The configuration principles used in JAX-RS client API apply toWebTarget as well. EachWebTarget 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, theFilterForExampleCom will be registered only in thewebTarget and not inclient. So, theclient can still be used to create newWebTarget instances pointing at other URIs using just the common client configuration, whichFilterForExampleCom filter is not part of.

Let's assume we have awebTarget 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, aWebTarget 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");

TheresourceWebTarget now points to the resource on URI"http://example.com/rest/resource". Again if we configure theresourceWebTarget with a filter specific to theresource, it will not influence the originalwebTarget instance. However, the filterFilterForExampleCom registration will still be inherited by theresourceWebTarget as it has been created fromwebTarget. This mechanism allows you to share the common configuration of related resources (typically hosted under the same URI root, in our case represented by thewebTarget 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 aWebTarget for this resource simply by:

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

Let's assume that thehelloworld resource accepts a query param forGET requests which defines the greeting message. The next code snippet shows a code that creates a newWebTarget with the query param defined.

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

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

Let's now focus on invoking aGET HTTP request on the created web targets. To start building a new HTTP request invocation, we need to create a newInvocation.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 therequest(...) methods that are available onWebTarget. 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 aAccept: text/plain HTTP header to our request.

TheinvocationBuilder 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 valuetrue.

Once finished with request customizations, it's time to invoke the request. We have two options now. We can use theInvocation.Builder to build a genericInvocation instance that will be invoked some time later. UsingInvocation 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-RSInvocation 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 customClientRequestFilter you can callgetProperty() method on the suppliedClientRequestContext to read a request property. Note that these request properties are different from the configuration properties set onConfigurable. As mentioned earlier, anInvocation instance provides generic invocation API to invoke the HTTP request it represents either synchronously or asynchronously. See theChapter 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 anInvocation.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 theinvocationBuilder. The URI of request will behttp://example.com/rest/resource/helloworld?greeting="Hi%20World!" and the request will containsome-header: true andAccept: text/plain headers. The request will then pass trough all configured request filters (AnotherClientFilter,ThirdClientFilter andFilterForExampleCom). 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 requestgreeting 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:

200Hi 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 aMyClientResponseFilter in the resource target, whenresponse.readEntity(String.class) gets called, the response returned from the remote endpoint is passed through the response filter chain (including theMyClientResponseFilter) and entity interceptor chain and at last a properMessageBodyReader<T> is located to read the response content bytes from the response stream into a JavaString instance. CheckChapter 10,Filters and Interceptors to lear more about request and response filters and entity interceptors.

Imagine now that you would like to invoke aPOST request but without any query parameters. You would just use thehelloworldWebTarget instance created earlier and call thepost() instead ofget().

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 genericResponse processing and directly requests an entity in the lastget(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 JavaString 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) andscheduledExecutorService(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 beManagedExecutorService andManagedScheduledExecutorService, for Java SE it would beForkJoinPool.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, namelyMessageBodyReader<T> andMessageBodyWriter<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 implementConfigurable contract (ClientBuilder,Client,WebTarget orClientConfig), as was shown in the earlier sections. Some media types are provided in the form of JAX-RSFeature 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.

Table 5.1. List of Jersey Connectors

Warning

Be aware of using other than defaultConnector implementation. There is an issue handling HTTP headers inWriterInterceptor orMessageBodyWriter<T>. If you need to change header fields do not use neitherApacheConnectorProvider norGrizzlyConnectorProvider norJettyConnectorProvider (for asynchronous requests). Other older version connectors can be affected by this issue as well. The issue for example applies to JerseyMultipart feature that also modifies HTTP headers.

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 theHttpUrlConnection

One limitation is in the variety of HTTP methods supported by theHttpUrlConnection, since only the original HTTP/1.1 methods are supported. For instance, HTTP Patch method is not supported. See propertyHttpUrlConnector.SET_METHOD_WORKAROUND in the AppendixSection A.6, “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 usesHttpUrlConnection 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 propertysun.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 theHttpUrlConnection is another aspect to consider. For details, seeJava Networking Properties, for instance propertyhttp.maxConnections.

For eachConnector a property file defining properties tweaking the actualConnector exists. There areClientProperties properties that apply to the defaultHttpUrlConnectorProvider. Many of the properties are also understood by variousConnectors. Each of theConnectorProvider defines properties that apply to it.

Moreover, eachConnector supports a list of properties that are unique for theConnector. The list of the client connector properties can be found in theAppendix 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);                        ...

Example 5.6. Closing connections

final WebTarget target = ... some web targetResponse response = target.path("resource").request().get();System.out.println("Connection is still open.");System.out.println("string response: " + response.readEntity(String.class));System.out.println("Now the connection is closed.");

Example 5.7. InjectionManagerClientProvider example

public static class MyRequestFilter implements ClientRequestFilter {    // this injection does not work as filter is registered as an instance:    // @Inject    // private MyInjectedService service;    @Override    public void filter(ClientRequestContext requestContext) throws IOException {        // use InjectionManagerClientProvider to extract InjectionManager from request        final InjectionManager injectionManager = InjectionManagerClientProvider.getInjectionManager(requestContext);        // and ask for MyInjectedService:        final MyInjectedService service = injectionManager.getInstance(MyInjectedService.class);        final String name = service.getName();        ...    }}

Important

A behaviour ofHostnameVerifier is dependent on an http client implementation.HttpUrlConnectorProvider andApacheConnectorProvider work properly, that means that after the unsuccessful URL verificationHostnameVerifier is called and by means of it is possible to revalidate URL using a custom implementation ofHostnameVerifier and go on in a handshake processing.JettyConnectorProvider andGrizzlyConnectorProvider provide only host URL verification and throw aCertificateException without any possibility to use customHostnameVerifier. Moreover, in case ofJettyConnectorProvider there is a propertyJettyClientProperties.ENABLE_SSL_HOSTNAME_VERIFICATION to disable an entire host URL verification mechanism in a handshake.

Important

Note that to utilize HTTP with SSL it is necessary to utilize the“https” scheme.

Jersey supports Basic and Digest HTTP Authentication.

In order to enable http authentication support in Jersey client register theHttpAuthenticationFeature. 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 theHttpAuthenticationFeature 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 theSNIHostName is required to be set for other host than the host specified in the HTTPS request. For those cases, when the HTTP headerHost is set, theSNIHostName is set for the host specified in theHost header. Note that onlyApache Connector, JDK Connector, Netty connector, and the defaultHttpUrlConnector do support this feature.

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

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

For this,PreInvocationInterceptor, the code that executes before theClientRequestFilters 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 toClientRequestFilter:

                /**                * 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 allPreInvocationInterceptors, otherwise anIllegalStateException is thrown. All the exceptions accumulated inPreInvocationInterceptors 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 toClientRequestFilter, the response filter may not be invoked at all. For this,PostInvocationInterceptor has been introduced. Jersey runtime ensures that everyPostInvocationInterceptor 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 consecutivePostInvocationInterceptor 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);

Important