mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-06 04:58:50 +00:00
a9fa5f2b33
This further applies the pattern set in #34125 to reduce copy-and-paste in the single document CRUD portion of the High Level REST Client docs. It also adds line wraps to snippets that are too wide to fit into the box when rendered in the docs, following up on the work started in #34163.
48 lines
2.0 KiB
Plaintext
48 lines
2.0 KiB
Plaintext
////
|
|
This file is included by every high level rest client API documentation page
|
|
so we don't have to copy and paste the same asciidoc over and over again. We
|
|
*do* have to copy and paste the same Java tests over and over again. For now
|
|
this is intentional because it forces us to *write* and execute the tests
|
|
which, while a bit ceremonial, does force us to cover these calls in *some*
|
|
test.
|
|
////
|
|
|
|
[id="{upid}-{api}-sync"]
|
|
==== Synchronous Execution
|
|
|
|
When executing a +{request}+ 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]
|
|
--------------------------------------------------
|
|
|
|
[id="{upid}-{api}-async"]
|
|
==== Asynchronous Execution
|
|
|
|
Executing a +{request}+ can also be done 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 the request and a listener to the
|
|
asynchronous {api} method:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests-file}[{api}-execute-async]
|
|
--------------------------------------------------
|
|
<1> The +{request}+ to execute and the `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.
|
|
|
|
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 whole +{request}+ fails. |