Skip to content

[DOCS] Document performRequestAsync #20217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 30, 2016
Merged

[DOCS] Document performRequestAsync #20217

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 72 additions & 15 deletions docs/java-rest/usage.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is it really not 2xx or is it 4xx or 5xx ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not 2xx as it currently exists:

return statusCode < 300 || (HttpHead.METHOD_NAME.equals(method) && statusCode == 404);

That honestly makes sense because it also excludes any possibility of 3xx.

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

Expand Down Expand Up @@ -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
Expand All @@ -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(),
Expand Down