102 lines
5.4 KiB
Plaintext
102 lines
5.4 KiB
Plaintext
== Common configuration
|
|
|
|
As explained in <<java-rest-low-usage-initialization>>, the `RestClientBuilder`
|
|
supports providing both a `RequestConfigCallback` and an `HttpClientConfigCallback`
|
|
which allow for any customization that the Apache Async Http Client exposes.
|
|
Those callbacks make it possible to modify some specific behaviour of the client
|
|
without overriding every other default configuration that the `RestClient`
|
|
is initialized with. This section describes some common scenarios that require
|
|
additional configuration for the low-level Java REST Client.
|
|
|
|
=== Timeouts
|
|
|
|
Configuring requests timeouts can be done by providing an instance of
|
|
`RequestConfigCallback` while building the `RestClient` through its builder.
|
|
The interface has one method that receives an instance of
|
|
https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/config/RequestConfig.Builder.html[`org.apache.http.client.config.RequestConfig.Builder`]
|
|
as an argument and has the same return type. The request config builder can
|
|
be modified and then returned. In the following example we increase the
|
|
connect timeout (defaults to 1 second) and the socket timeout (defaults to 30
|
|
seconds). Also we adjust the max retry timeout accordingly (defaults to 30
|
|
seconds too).
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-config-timeouts]
|
|
--------------------------------------------------
|
|
|
|
=== Number of threads
|
|
|
|
The Apache Http Async Client starts by default one dispatcher thread, and a
|
|
number of worker threads used by the connection manager, as many as the number
|
|
of locally detected processors (depending on what
|
|
`Runtime.getRuntime().availableProcessors()` returns). The number of threads
|
|
can be modified as follows:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-config-threads]
|
|
--------------------------------------------------
|
|
|
|
=== Basic authentication
|
|
|
|
Configuring basic authentication can be done by providing an
|
|
`HttpClientConfigCallback` while building the `RestClient` through its builder.
|
|
The interface has one method that receives an instance of
|
|
https://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html[`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`]
|
|
as an argument and has the same return type. The http client builder can be
|
|
modified and then returned. In the following example we set a default
|
|
credentials provider that requires basic authentication.
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-config-basic-auth]
|
|
--------------------------------------------------
|
|
|
|
Preemptive Authentication can be disabled, which means that every request will be sent without
|
|
authorization headers to see if it is accepted and, upon receiving a HTTP 401 response, it will
|
|
resend the exact same request with the basic authentication header. If you wish to do this, then
|
|
you can do so by disabling it via the `HttpAsyncClientBuilder`:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-config-disable-preemptive-auth]
|
|
--------------------------------------------------
|
|
<1> Disable preemptive authentication
|
|
|
|
=== Encrypted communication
|
|
|
|
Encrypted communication can also be configured through the
|
|
`HttpClientConfigCallback`. The
|
|
https://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html[`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`]
|
|
received as an argument exposes multiple methods to configure encrypted
|
|
communication: `setSSLContext`, `setSSLSessionStrategy` and
|
|
`setConnectionManager`, in order of precedence from the least important.
|
|
The following is an example:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-config-encrypted-communication]
|
|
--------------------------------------------------
|
|
|
|
If no explicit configuration is provided, the http://docs.oracle.com/javase/7/docs/technotes/guides/security/jsse/JSSERefGuide.html#CustomizingStores[system default configuration]
|
|
will be used.
|
|
|
|
=== Others
|
|
|
|
For any other required configuration needed, the Apache HttpAsyncClient docs
|
|
should be consulted: https://hc.apache.org/httpcomponents-asyncclient-4.1.x/ .
|
|
|
|
NOTE: If your application runs under the security manager you might be subject
|
|
to the JVM default policies of caching positive hostname resolutions
|
|
indefinitely and negative hostname resolutions for ten seconds. If the resolved
|
|
addresses of the hosts to which you are connecting the client to vary with time
|
|
then you might want to modify the default JVM behavior. These can be modified by
|
|
adding
|
|
http://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.html[`networkaddress.cache.ttl=<timeout>`]
|
|
and
|
|
http://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.html[`networkaddress.cache.negative.ttl=<timeout>`]
|
|
to your
|
|
http://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html[Java
|
|
security policy].
|