From 91dc1c5da682fd832fc27d07f657643a88f4aae5 Mon Sep 17 00:00:00 2001 From: Tanguy Leroux Date: Wed, 26 Jul 2017 12:17:21 +0200 Subject: [PATCH] [Docs] Update Java Low-Level documentation to reflect shaded deps (#25882) Since #25208 the Java Low-Level Rest Client has shaded dependencies. This commit updates the documentation to reflect that. --- .../low-level/configuration.asciidoc | 12 +++--- docs/java-rest/low-level/index.asciidoc | 4 +- docs/java-rest/low-level/usage.asciidoc | 40 +++++++++---------- 3 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/java-rest/low-level/configuration.asciidoc b/docs/java-rest/low-level/configuration.asciidoc index 54f7cd28173..a9aeb624854 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 -https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/config/RequestConfig.Builder.html[`org.apache.http.client.config.RequestConfig.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]) 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 -https://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html[`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`] +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]) 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 -https://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html[`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`] +`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]) 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 92230a657a9..5c17d6e5e04 100644 --- a/docs/java-rest/low-level/index.asciidoc +++ b/docs/java-rest/low-level/index.asciidoc @@ -6,8 +6,6 @@ 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 @@ -22,6 +20,8 @@ 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 78c153adff0..4e6152bddcc 100644 --- a/docs/java-rest/low-level/usage.asciidoc +++ b/docs/java-rest/low-level/usage.asciidoc @@ -48,10 +48,7 @@ dependencies { [[java-rest-low-usage-dependencies]] === Dependencies -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: +The low-level Java REST client uses several https://www.apache.org/[Apache] libraries: - org.apache.httpcomponents:httpasyncclient - org.apache.httpcomponents:httpcore-nio @@ -61,6 +58,13 @@ http://hc.apache.org/httpcomponents-asyncclient-dev/[Apache Http Async Client] - 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 @@ -117,18 +121,16 @@ 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 -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) +(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] ["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 -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) +(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] [[java-rest-low-usage-requests]] @@ -162,7 +164,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.apache.http.HttpEntity` +parameters and the request body enclosed in an `org.elasticsearch.client.http.HttpEntity` object IMPORTANT: The `ContentType` specified for the `HttpEntity` is important @@ -175,7 +177,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 an http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.html[`org.apache.http.nio.protocol.HttpAsyncResponseConsumer`] +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]) 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 @@ -205,7 +207,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.apache.http.HttpEntity` object and the response listener to be +`org.elasticsearch.client.http.HttpEntity` object and the response listener to be notified once the request is completed ["source","java",subs="attributes,callouts,macros"] @@ -214,7 +216,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 an http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.html[`org.apache.http.nio.protocol.HttpAsyncResponseConsumer`] +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]) 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 @@ -258,8 +260,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 an https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/HttpEntity.html[`org.apache.http.HttpEntity`] - object +<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] When performing a request, an exception is thrown (or received as an argument in `ResponseListener#onFailure(Exception)` in the following scenarios: @@ -286,14 +288,12 @@ 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 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`] +The low-level Java Rest Client ships with different `org.elasticsearch.client.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 -http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.html[`org.apache.http.nio.protocol.HttpAsyncResponseConsumer`] +possible to provide a custom org.elasticsearch.client.http.nio.protocol.HttpAsyncResponseConsumer` that controls how bytes are read and buffered. [[java-rest-low-usage-logging]]