[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.
This commit is contained in:
Tanguy Leroux
GitHub
parent
9d10dbea39
commit
91dc1c5da6
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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 <<sniffer,discovery of cluster nodes>>
|
||||
|
||||
* packaged as a single JAR file that shades all dependencies
|
||||
|
||||
--
|
||||
|
||||
:doc-tests: {docdir}/../../client/rest/src/test/java/org/elasticsearch/client/documentation
|
||||
|
|
|
|||
|
|
@ -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]]
|
||||
|
|
|
|||
Loading…
Reference in New Issue