|
|
@@ -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]]
|
Michael Basnight