2018-09-28 14:48:11 -04:00
|
|
|
////
|
|
|
|
|
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.
|
|
|
|
|
|
2018-10-05 11:41:03 -04:00
|
|
|
A typical listener for +{api}+ looks like:
|
2018-09-28 14:48:11 -04:00
|
|
|
|
|
|
|
|
["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.
|
