diff --git a/docs/java-rest/usage.asciidoc b/docs/java-rest/usage.asciidoc index 69f95413a708..55eac8e4668a 100644 --- a/docs/java-rest/usage.asciidoc +++ b/docs/java-rest/usage.asciidoc @@ -90,16 +90,67 @@ http://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/ === Performing requests Once the `RestClient` has been created, requests can be sent by calling one of -the available `performRequest` method variants. The ones that return the -`Response` are executed synchronously, meaning that the client will block and -wait for a response to be returned. The `performRequest` variants that return -`void` accept a `ResponseListener` as an argument and are executed -asynchronously. The provided listener will be notified upon completion or -failure. The following are the arguments accepted by the different -`performRequest` methods: +the available `performRequest` or `performRequestAsync` method variants. +The `performRequest` methods are synchronous and they return the `Response` +directly, meaning that the client will block and wait for a response to be returned. +The `performRequestAsync` variants, which return `void` and accept an extra +`ResponseListener` as an argument, are executed asynchronously. The provided +listener will be notified upon completion or failure. + +[source,java] +-------------------------------------------------- +// Synchronous variants +Response performRequest(String method, String endpoint, + Header... headers) + throws IOException; + +Response performRequest(String method, String endpoint, + Map params, Header... headers) + throws IOException; + +Response performRequest(String method, String endpoint, + Map params, + HttpEntity entity, + Header... headers) + throws IOException; + +Response performRequest(String method, String endpoint, + Map params, + HttpEntity entity, + HttpAsyncResponseConsumer responseConsumer, + Header... headers) + throws IOException; + +// Asynchronous variants +void performRequestAsync(String method, String endpoint, + ResponseListener responseListener, + Header... headers); + +void performRequestAsync(String method, String endpoint, + Map params, + ResponseListener responseListener, + Header... headers); + +void performRequestAsync(String method, String endpoint, + Map params, + HttpEntity entity, + ResponseListener responseListener, + Header... headers); + +void performRequestAsync(String method, String endpoint, + Map params, + HttpEntity entity, + ResponseListener responseListener, + HttpAsyncResponseConsumer responseConsumer, + Header... headers); +-------------------------------------------------- + +==== Request Arguments + +The following are the arguments accepted by the different methods: `method`:: the http method or verb -`endpoint`:: the request path, which identifies the Elasticsearch api to +`endpoint`:: the request path, which identifies the Elasticsearch API to call (e.g. `/_cluster/health`) `params`:: the optional parameters to be sent as querystring parameters `entity`:: the optional request body enclosed in an @@ -109,14 +160,14 @@ http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http callback. 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 body in heap memory -`responseListener`:: the listener to be notified upon request success or failure -whenever the async `performRequest` method variants are used +`responseListener`:: the listener to be notified upon asynchronous +request success or failure `headers`:: optional request headers === Reading responses -The `Response` object, either returned by the sync `performRequest` methods or - received as an argument in `ResponseListener#onSucces(Response)`, wraps the +The `Response` object, either returned by the synchronous `performRequest` methods or +received as an argument in `ResponseListener#onSuccess(Response)`, wraps the response object returned by the http client and exposes the following information: `getRequestLine`:: information about the performed request @@ -129,14 +180,19 @@ https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/Ht object When performing a request, an exception is thrown (or received as an argument - in `ResponseListener#onSucces(Exception)` in the following scenarios: + in `ResponseListener#onFailure(Exception)` in the following scenarios: `IOException`:: communication problem (e.g. SocketTimeoutException etc.) `ResponseException`:: a response was returned, but its status code indicated -an error (either `4xx` or `5xx`). A `ResponseException` originates from a valid +an error (not `2xx`). A `ResponseException` originates from a valid http response, hence it exposes its corresponding `Response` object which gives access to the returned response. +NOTE: A `ResponseException` is **not** thrown for `HEAD` requests that return +a `404` status code because it is an expected `HEAD` response that simply +denotes that the resource is not found. All other HTTP methods (e.g., `GET`) +throw a `ResponseException` for `404` responses. + === Example requests @@ -167,6 +223,7 @@ Response indexResponse = restClient.performRequest( 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`] implementations that allow to provide the request body in different formats @@ -184,7 +241,7 @@ The following is a basic example of how async requests can be sent: int numRequests = 10; final CountDownLatch latch = new CountDownLatch(numRequests); for (int i = 0; i < numRequests; i++) { - restClient.performRequest( + restClient.performRequestAsync( "PUT", "/twitter/tweet/" + i, Collections.emptyMap(),