[DOCS] Document performRequest being renamed to performRequestAsync
This updates the docs to reflect that the asynchronous variants were renamed to have "Async" at the end.
This commit is contained in:
Chris Earle
parent
df73292256
commit
6ad92c0f9d
|
|
@ -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<String, String> params, Header... headers)
|
||||
throws IOException;
|
||||
|
||||
Response performRequest(String method, String endpoint,
|
||||
Map<String, String> params,
|
||||
HttpEntity entity,
|
||||
Header... headers)
|
||||
throws IOException;
|
||||
|
||||
Response performRequest(String method, String endpoint,
|
||||
Map<String, String> params,
|
||||
HttpEntity entity,
|
||||
HttpAsyncResponseConsumer<HttpResponse> responseConsumer,
|
||||
Header... headers)
|
||||
throws IOException;
|
||||
|
||||
// Asynchronous variants
|
||||
void performRequestAsync(String method, String endpoint,
|
||||
ResponseListener responseListener,
|
||||
Header... headers);
|
||||
|
||||
void performRequestAsync(String method, String endpoint,
|
||||
Map<String, String> params,
|
||||
ResponseListener responseListener,
|
||||
Header... headers);
|
||||
|
||||
void performRequestAsync(String method, String endpoint,
|
||||
Map<String, String> params,
|
||||
HttpEntity entity,
|
||||
ResponseListener responseListener,
|
||||
Header... headers);
|
||||
|
||||
void performRequestAsync(String method, String endpoint,
|
||||
Map<String, String> params,
|
||||
HttpEntity entity,
|
||||
ResponseListener responseListener,
|
||||
HttpAsyncResponseConsumer<HttpResponse> 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.<String, String>emptyMap(),
|
||||
|
|
|
|||
Loading…
Reference in New Issue