56 lines
2.3 KiB
Plaintext
56 lines
2.3 KiB
Plaintext
|
////
|
||
|
|
This file is included by high level rest client API documentation pages
|
||
|
|
where the client method does not use a request object.
|
||
|
|
For methods with requests, see execution.asciidoc
|
||
|
|
////
|
||
|
|
|
||
|
|
[id="{upid}-{api}-sync"]
|
||
|
|
==== Synchronous Execution
|
||
|
|
|
||
|
|
When executing the +{api}+ API in the following manner, the client waits
|
||
|
|
for the +{response}+ to be returned before continuing with code execution:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests-file}[{api}-execute]
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
Synchronous calls may throw an `IOException` in case of either failing to
|
||
|
|
parse the REST response in the high-level REST client, the request times out
|
||
|
|
or similar cases where there is no response coming back from the server.
|
||
|
|
|
||
|
|
In cases where the server returns a `4xx` or `5xx` error code, the high-level
|
||
|
|
client tries to parse the response body error details instead and then throws
|
||
|
|
a generic `ElasticsearchException` and adds the original `ResponseException` as a
|
||
|
|
suppressed exception to it.
|
||
|
|
|
||
|
|
[id="{upid}-{api}-async"]
|
||
|
|
==== Asynchronous Execution
|
||
|
|
|
||
|
|
The +{api}+ API can also be called in an asynchronous fashion so that
|
||
|
|
the client can return directly. Users need to specify how the response or
|
||
|
|
potential failures will be handled by passing a listener to the
|
||
|
|
asynchronous {api} method:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests-file}[{api}-execute-async]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> The `RequestOptions` and `ActionListener` to use when the execution
|
||
|
|
completes
|
||
|
|
|
||
|
|
The asynchronous method does not block and returns immediately. Once it is
|
||
|
|
completed the `ActionListener` is called back using the `onResponse` method
|
||
|
|
if the execution successfully completed or using the `onFailure` method if
|
||
|
|
it failed. Failure scenarios and expected exceptions are the same as in the
|
||
|
|
synchronous execution case.
|
||
|
|
|
||
|
|
A typical listener for +{api}+ looks like:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests-file}[{api}-execute-listener]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> Called when the execution is successfully completed.
|
||
|
|
<2> Called when the +{api}+ call fails.
|