diff --git a/docs/java-rest/low-level/configuration.asciidoc b/docs/java-rest/low-level/configuration.asciidoc index a9aeb624854..54f7cd28173 100644 --- a/docs/java-rest/low-level/configuration.asciidoc +++ b/docs/java-rest/low-level/configuration.asciidoc @@ -12,8 +12,8 @@ additional configuration for the low-level Java REST Client. 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 `org.elasticsearch.client.http.client.config.RequestConfig.Builder` -(see the https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/config/RequestConfig.Builder.html[Apache documentation]) +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 @@ -42,8 +42,8 @@ include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-config-thre 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 `org.elasticsearch.client.http.impl.nio.client.HttpAsyncClientBuilder` -(see the https://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html[Apache documentation]) +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. @@ -67,8 +67,8 @@ include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-config-disa === Encrypted communication Encrypted communication can also be configured through the -`HttpClientConfigCallback`. The `org.elasticsearch.client.http.impl.nio.client.HttpAsyncClientBuilder` -(see the https://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html[Apache documentation]) +`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. diff --git a/docs/java-rest/low-level/index.asciidoc b/docs/java-rest/low-level/index.asciidoc index 5c17d6e5e04..92230a657a9 100644 --- a/docs/java-rest/low-level/index.asciidoc +++ b/docs/java-rest/low-level/index.asciidoc @@ -6,6 +6,8 @@ The low-level client's features include: +* minimal dependencies + * load balancing across all available nodes * failover in case of node failures and upon specific response codes @@ -20,8 +22,6 @@ The low-level client's features include: * optional automatic <> -* packaged as a single JAR file that shades all dependencies - -- :doc-tests: {docdir}/../../client/rest/src/test/java/org/elasticsearch/client/documentation diff --git a/docs/java-rest/low-level/usage.asciidoc b/docs/java-rest/low-level/usage.asciidoc index c9664613cca..7dbec495b28 100644 --- a/docs/java-rest/low-level/usage.asciidoc +++ b/docs/java-rest/low-level/usage.asciidoc @@ -53,7 +53,10 @@ dependencies { [[java-rest-low-usage-dependencies]] === Dependencies -The low-level Java REST client uses several https://www.apache.org/[Apache] libraries: +The low-level Java REST client internally uses the +http://hc.apache.org/httpcomponents-asyncclient-dev/[Apache Http Async Client] + to send http requests. It depends on the following artifacts, namely the async + http client and its own transitive dependencies: - org.apache.httpcomponents:httpasyncclient - org.apache.httpcomponents:httpcore-nio @@ -63,13 +66,6 @@ The low-level Java REST client uses several https://www.apache.org/[Apache] libr - commons-logging:commons-logging -One of the most important is the http://hc.apache.org/httpcomponents-asyncclient-dev/[Apache Http Async Client] - which is used to send http requests. In order to avoid version conflicts, these dependencies are shaded and - packaged within the client in a single JAR file (sometimes called "uber jar" or "fat jar"). Shading a dependency - consists of taking its content (resources files and Java class files), rename its packages (all package names - that start with `org.apache` are renamed to `org.elasticsearch.client`) before putting them in the same JAR file -as the low-level Java REST client. - [[java-rest-low-usage-initialization]] === Initialization @@ -126,16 +122,18 @@ need to be taken. Used internally when sniffing on failure is enabled. include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-init-request-config-callback] -------------------------------------------------- <1> Set a callback that allows to modify the default request configuration -(e.g. request timeouts, authentication, or anything that the `org.elasticsearch.client.http.client.config.RequestConfig.Builder` -allows to set). For more information, see the https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/config/RequestConfig.Builder.html[Apache documentation] +(e.g. request timeouts, authentication, or anything that the +https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/config/RequestConfig.Builder.html[`org.apache.http.client.config.RequestConfig.Builder`] + allows to set) ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-init-client-config-callback] -------------------------------------------------- <1> Set a callback that allows to modify the http client configuration -(e.g. encrypted communication over ssl, or anything that the `org.elasticsearch.client.http.impl.nio.client.HttpAsyncClientBuilder` - allows to set). For more information, see the http://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html[Apache documentation] +(e.g. encrypted communication over ssl, or anything that the +http://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html[`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`] + allows to set) [[java-rest-low-usage-requests]] @@ -169,7 +167,7 @@ parameter include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-verb-endpoint-params-body] -------------------------------------------------- <1> Send a request by providing the verb, the endpoint, optional querystring -parameters and the request body enclosed in an `org.elasticsearch.client.http.HttpEntity` +parameters and the request body enclosed in an `org.apache.http.HttpEntity` object IMPORTANT: The `ContentType` specified for the `HttpEntity` is important @@ -182,7 +180,7 @@ include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-response-co -------------------------------------------------- <1> Send a request by providing the verb, the endpoint, optional querystring parameters, optional request body and the optional factory that is used to -create a `org.elasticsearch.client.http.nio.protocol.HttpAsyncResponseConsumer` (see the http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.html[Apache documentation]) +create an http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.html[`org.apache.http.nio.protocol.HttpAsyncResponseConsumer`] callback instance per request attempt. Controls how the response body gets streamed from a non-blocking HTTP connection on the client side. When not provided, the default implementation is used which buffers the whole response @@ -212,7 +210,7 @@ include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-verb-endpoi -------------------------------------------------- <1> Send an async request by providing the verb, the endpoint, optional querystring parameters, the request body enclosed in an -`org.elasticsearch.client.http.HttpEntity` object and the response listener to be +`org.apache.http.HttpEntity` object and the response listener to be notified once the request is completed ["source","java",subs="attributes,callouts,macros"] @@ -221,7 +219,7 @@ include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-response-co -------------------------------------------------- <1> Send an async request by providing the verb, the endpoint, optional querystring parameters, optional request body and the optional factory that is -used to create a `org.elasticsearch.client.http.nio.protocol.HttpAsyncResponseConsumer` (see the http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.html[Apache documentation]) +used to create an http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.html[`org.apache.http.nio.protocol.HttpAsyncResponseConsumer`] callback instance per request attempt. Controls how the response body gets streamed from a non-blocking HTTP connection on the client side. When not provided, the default implementation is used which buffers the whole response @@ -265,8 +263,8 @@ include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-response2] <2> The host that returned the response <3> The response status line, from which you can for instance retrieve the status code <4> The response headers, which can also be retrieved by name though `getHeader(String)` -<5> The response body enclosed in a `org.elasticsearch.client.http.HttpEntity` object -(see the https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/HttpEntity.html[Apache documentation] +<5> The response body enclosed in an https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/HttpEntity.html[`org.apache.http.HttpEntity`] + object When performing a request, an exception is thrown (or received as an argument in `ResponseListener#onFailure(Exception)` in the following scenarios: @@ -293,12 +291,14 @@ Note that the low-level client doesn't expose any helper for json marshalling and un-marshalling. Users are free to use the library that they prefer for that purpose. -The low-level Java Rest Client ships with different `org.elasticsearch.client.http.HttpEntity` +The underlying Apache Async Http Client ships with different +https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/HttpEntity.html[`org.apache.http.HttpEntity`] implementations that allow to provide the request body in different formats (stream, byte array, string etc.). As for reading the response body, the `HttpEntity#getContent` method comes handy which returns an `InputStream` reading from the previously buffered response body. As an alternative, it is -possible to provide a custom org.elasticsearch.client.http.nio.protocol.HttpAsyncResponseConsumer` +possible to provide a custom +http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.html[`org.apache.http.nio.protocol.HttpAsyncResponseConsumer`] that controls how bytes are read and buffered. [[java-rest-low-usage-logging]]