[Docs] Docs tests should wait for async execution to complete (#28481)

This commit splits the async execution documentation into 2 parts, one
for the async method itself and one for the action listener. This allows
to add more doc and to use CountDownLatches in doc tests to wait for
asynchronous operations to be completed before moving to the next test.

It also renames few files.

Related to #28457

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java

@@ -27,6 +27,7 @@ import org.elasticsearch.ElasticsearchException;
 import org.elasticsearch.action.ActionListener;
 import org.elasticsearch.action.DocWriteRequest;
 import org.elasticsearch.action.DocWriteResponse;
+import org.elasticsearch.action.LatchedActionListener;
 import org.elasticsearch.action.bulk.BackoffPolicy;
 import org.elasticsearch.action.bulk.BulkItemResponse;
 import org.elasticsearch.action.bulk.BulkProcessor;
@@ -65,6 +66,7 @@ import java.util.Collections;
 import java.util.Date;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 
 import static java.util.Collections.emptyMap;
@@ -86,6 +88,7 @@ import static java.util.Collections.singletonMap;
  */
 public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
 
+    @SuppressWarnings({"unchecked", "rawtypes"})
     public void testIndex() throws Exception {
         RestHighLevelClient client = highLevelClient();
 
@@ -227,9 +230,8 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
         }
         {
             IndexRequest request = new IndexRequest("posts", "doc", "async").source("field", "value");
-
-            // tag::index-execute-async
-            client.indexAsync(request, new ActionListener<IndexResponse>() {
+            // tag::index-execute-listener
+            ActionListener<IndexResponse> listener = new ActionListener<IndexResponse>() {
                 @Override
                 public void onResponse(IndexResponse indexResponse) {
                     // <1>
@@ -239,13 +241,22 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::index-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::index-execute-async
+            client.indexAsync(request, listener); // <1>
             // end::index-execute-async
 
-            assertBusy(() -> assertTrue(client.exists(new GetRequest("posts", "doc", "async"))));
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
     }
 
+    @SuppressWarnings({"unchecked", "rawtypes"})
     public void testUpdate() throws Exception {
         RestHighLevelClient client = highLevelClient();
         {
@@ -490,8 +501,8 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
         {
             UpdateRequest request = new UpdateRequest("posts", "doc", "async").doc("reason", "async update").docAsUpsert(true);
 
-            // tag::update-execute-async
-            client.updateAsync(request, new ActionListener<UpdateResponse>() {
+            // tag::update-execute-listener
+            ActionListener<UpdateResponse> listener = new ActionListener<UpdateResponse>() {
                 @Override
                 public void onResponse(UpdateResponse updateResponse) {
                     // <1>
@@ -501,13 +512,22 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::update-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::update-execute-async
+            client.updateAsync(request, listener); // <1>
             // end::update-execute-async
 
-            assertBusy(() -> assertTrue(client.exists(new GetRequest("posts", "doc", "async"))));
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
     }
 
+    @SuppressWarnings({"unchecked", "rawtypes"})
     public void testDelete() throws Exception {
         RestHighLevelClient client = highLevelClient();
 
@@ -602,8 +622,8 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
 
             DeleteRequest request = new DeleteRequest("posts", "doc", "async");
 
-            // tag::delete-execute-async
-            client.deleteAsync(request, new ActionListener<DeleteResponse>() {
+            // tag::delete-execute-listener
+            ActionListener<DeleteResponse> listener = new ActionListener<DeleteResponse>() {
                 @Override
                 public void onResponse(DeleteResponse deleteResponse) {
                     // <1>
@@ -613,14 +633,23 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::delete-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::delete-execute-async
+            client.deleteAsync(request, listener); // <1>
             // end::delete-execute-async
 
-            assertBusy(() -> assertFalse(client.exists(new GetRequest("posts", "doc", "async"))));
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
     }
 
-    public void testBulk() throws IOException {
+    @SuppressWarnings({"unchecked", "rawtypes"})
+    public void testBulk() throws Exception {
         RestHighLevelClient client = highLevelClient();
         {
             // tag::bulk-request
@@ -696,8 +725,8 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
             request.waitForActiveShards(ActiveShardCount.ALL); // <2>
             // end::bulk-request-active-shards
 
-            // tag::bulk-execute-async
-            client.bulkAsync(request, new ActionListener<BulkResponse>() {
+            // tag::bulk-execute-listener
+            ActionListener<BulkResponse> listener = new ActionListener<BulkResponse>() {
                 @Override
                 public void onResponse(BulkResponse bulkResponse) {
                     // <1>
@@ -707,12 +736,23 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::bulk-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::bulk-execute-async
+            client.bulkAsync(request, listener); // <1>
             // end::bulk-execute-async
+
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
     }
 
-    public void testGet() throws IOException {
+    @SuppressWarnings({"unchecked", "rawtypes"})
+    public void testGet() throws Exception {
         RestHighLevelClient client = highLevelClient();
         {
             String mappings = "{\n" +
@@ -839,8 +879,9 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
         }
         {
             GetRequest request = new GetRequest("posts", "doc", "1");
-            //tag::get-execute-async
-            client.getAsync(request, new ActionListener<GetResponse>() {
+
+            // tag::get-execute-listener
+            ActionListener<GetResponse> listener = new ActionListener<GetResponse>() {
                 @Override
                 public void onResponse(GetResponse getResponse) {
                     // <1>
@@ -850,8 +891,18 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::get-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            //tag::get-execute-async
+            client.getAsync(request, listener); // <1>
             //end::get-execute-async
+
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
         {
             //tag::get-indexnotfound

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java

@@ -21,6 +21,7 @@ package org.elasticsearch.client.documentation;
 
 import org.elasticsearch.ElasticsearchException;
 import org.elasticsearch.action.ActionListener;
+import org.elasticsearch.action.LatchedActionListener;
 import org.elasticsearch.action.admin.indices.alias.Alias;
 import org.elasticsearch.action.admin.indices.alias.IndicesAliasesRequest;
 import org.elasticsearch.action.admin.indices.alias.IndicesAliasesRequest.AliasActions;
@@ -42,7 +43,6 @@ import org.elasticsearch.action.admin.indices.shrink.ResizeType;
 import org.elasticsearch.action.support.ActiveShardCount;
 import org.elasticsearch.action.support.IndicesOptions;
 import org.elasticsearch.client.ESRestHighLevelClientTestCase;
-import org.elasticsearch.client.Response;
 import org.elasticsearch.client.RestHighLevelClient;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.unit.TimeValue;
@@ -51,6 +51,8 @@ import org.elasticsearch.rest.RestStatus;
 
 import java.io.IOException;
 import java.util.Map;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
 
 /**
  * This class is used to generate the Java Indices API documentation.
@@ -117,6 +119,7 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
         }
     }
 
+    @SuppressWarnings({"unchecked", "rawtypes"})
     public void testDeleteIndexAsync() throws Exception {
         final RestHighLevelClient client = highLevelClient();
 
@@ -128,8 +131,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
         {
             DeleteIndexRequest request = new DeleteIndexRequest("posts");
 
-            // tag::delete-index-execute-async
-            client.indices().deleteAsync(request, new ActionListener<DeleteIndexResponse>() {
+            // tag::delete-index-execute-listener
+            ActionListener<DeleteIndexResponse> listener = new ActionListener<DeleteIndexResponse>() {
                 @Override
                 public void onResponse(DeleteIndexResponse deleteIndexResponse) {
                     // <1>
@@ -139,14 +142,18 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::delete-index-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::delete-index-execute-async
+            client.indices().deleteAsync(request, listener); // <1>
             // end::delete-index-execute-async
 
-            assertBusy(() -> {
-                // TODO Use Indices Exist API instead once it exists
-                Response response = client.getLowLevelClient().performRequest("HEAD", "posts");
-                assertTrue(RestStatus.NOT_FOUND.getStatus() == response.getStatusLine().getStatusCode());
-            });
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
     }
 
@@ -211,13 +218,15 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
         }
     }
 
+    @SuppressWarnings({"unchecked", "rawtypes"})
     public void testCreateIndexAsync() throws Exception {
         final RestHighLevelClient client = highLevelClient();
 
         {
             CreateIndexRequest request = new CreateIndexRequest("twitter");
-            // tag::create-index-execute-async
-            client.indices().createAsync(request, new ActionListener<CreateIndexResponse>() {
+
+            // tag::create-index-execute-listener
+            ActionListener<CreateIndexResponse> listener = new ActionListener<CreateIndexResponse>() {
                 @Override
                 public void onResponse(CreateIndexResponse createIndexResponse) {
                     // <1>
@@ -227,14 +236,18 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::create-index-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::create-index-execute-async
+            client.indices().createAsync(request, listener); // <1>
             // end::create-index-execute-async
 
-            assertBusy(() -> {
-                // TODO Use Indices Exist API instead once it exists
-                Response response = client.getLowLevelClient().performRequest("HEAD", "twitter");
-                assertTrue(RestStatus.OK.getStatus() == response.getStatusLine().getStatusCode());
-            });
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
     }
 
@@ -286,6 +299,7 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
         }
     }
 
+    @SuppressWarnings({"unchecked", "rawtypes"})
     public void testPutMappingAsync() throws Exception {
         final RestHighLevelClient client = highLevelClient();
 
@@ -296,8 +310,9 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
 
         {
             PutMappingRequest request = new PutMappingRequest("twitter").type("tweet");
-            // tag::put-mapping-execute-async
-            client.indices().putMappingAsync(request, new ActionListener<PutMappingResponse>() {
+
+            // tag::put-mapping-execute-listener
+            ActionListener<PutMappingResponse> listener = new ActionListener<PutMappingResponse>() {
                 @Override
                 public void onResponse(PutMappingResponse putMappingResponse) {
                     // <1>
@@ -307,11 +322,22 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::put-mapping-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::put-mapping-execute-async
+            client.indices().putMappingAsync(request, listener); // <1>
             // end::put-mapping-execute-async
+
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
     }
 
+    @SuppressWarnings({"unchecked", "rawtypes"})
     public void testOpenIndex() throws Exception {
         RestHighLevelClient client = highLevelClient();
 
@@ -353,8 +379,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
             assertTrue(acknowledged);
             assertTrue(shardsAcked);
 
-            // tag::open-index-execute-async
-            client.indices().openAsync(request, new ActionListener<OpenIndexResponse>() {
+            // tag::open-index-execute-listener
+            ActionListener<OpenIndexResponse> listener = new ActionListener<OpenIndexResponse>() {
                 @Override
                 public void onResponse(OpenIndexResponse openIndexResponse) {
                     // <1>
@@ -364,14 +390,18 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::open-index-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::open-index-execute-async
+            client.indices().openAsync(request, listener); // <1>
             // end::open-index-execute-async
 
-            assertBusy(() -> {
-                // TODO Use Indices Exist API instead once it exists
-                Response response = client.getLowLevelClient().performRequest("HEAD", "index");
-                assertTrue(RestStatus.OK.getStatus() == response.getStatusLine().getStatusCode());
-            });
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
 
         {
@@ -388,6 +418,7 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
         }
     }
 
+    @SuppressWarnings({"unchecked", "rawtypes"})
     public void testCloseIndex() throws Exception {
         RestHighLevelClient client = highLevelClient();
 
@@ -423,8 +454,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
             // end::close-index-response
             assertTrue(acknowledged);
 
-            // tag::close-index-execute-async
-            client.indices().closeAsync(request, new ActionListener<CloseIndexResponse>() {
+            // tag::close-index-execute-listener
+            ActionListener<CloseIndexResponse> listener = new ActionListener<CloseIndexResponse>() {
                 @Override
                 public void onResponse(CloseIndexResponse closeIndexResponse) {
                     // <1>
@@ -434,12 +465,22 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::close-index-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::close-index-execute-async
+            client.indices().closeAsync(request, listener); // <1>
             // end::close-index-execute-async
 
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
     }
 
+    @SuppressWarnings({"unchecked", "rawtypes"})
     public void testExistsAlias() throws Exception {
         RestHighLevelClient client = highLevelClient();
 
@@ -476,8 +517,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
             // end::exists-alias-execute
             assertTrue(exists);
 
-            // tag::exists-alias-execute-async
-            client.indices().existsAliasAsync(request, new ActionListener<Boolean>() {
+            // tag::exists-alias-listener
+            ActionListener<Boolean> listener = new ActionListener<Boolean>() {
                 @Override
                 public void onResponse(Boolean exists) {
                     // <1>
@@ -487,11 +528,22 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::exists-alias-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::exists-alias-execute-async
+            client.indices().existsAliasAsync(request, listener); // <1>
             // end::exists-alias-execute-async
+
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
     }
 
+    @SuppressWarnings({"unchecked", "rawtypes"})
     public void testUpdateAliases() throws Exception {
         RestHighLevelClient client = highLevelClient();
 
@@ -545,8 +597,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
             AliasActions aliasAction = new AliasActions(AliasActions.Type.ADD).index("index1").alias("async"); // <2>
             request.addAliasAction(aliasAction);
 
-            // tag::update-aliases-execute-async
-            client.indices().updateAliasesAsync(request, new ActionListener<IndicesAliasesResponse>() {
+            // tag::update-aliases-execute-listener
+            ActionListener<IndicesAliasesResponse> listener = new ActionListener<IndicesAliasesResponse>() {
                 @Override
                 public void onResponse(IndicesAliasesResponse indicesAliasesResponse) {
                     // <1>
@@ -556,15 +608,23 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::update-aliases-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::update-aliases-execute-async
+            client.indices().updateAliasesAsync(request, listener); // <1>
             // end::update-aliases-execute-async
 
-            assertBusy(() -> assertTrue(client.indices().existsAlias(new GetAliasesRequest("async"))));
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
     }
 
-    @SuppressWarnings("unchecked")
-    public void testShrinkIndex() throws IOException {
+    @SuppressWarnings({"unchecked", "rawtypes"})
+    public void testShrinkIndex() throws Exception {
         RestHighLevelClient client = highLevelClient();
 
         {
@@ -609,8 +669,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
         assertTrue(acknowledged);
         assertTrue(shardsAcked);
 
-        // tag::shrink-index-execute-async
-        client.indices().shrinkAsync(request, new ActionListener<ResizeResponse>() {
+        // tag::shrink-index-execute-listener
+        ActionListener<ResizeResponse> listener = new ActionListener<ResizeResponse>() {
             @Override
             public void onResponse(ResizeResponse resizeResponse) {
                 // <1>
@@ -620,12 +680,22 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
             public void onFailure(Exception e) {
                 // <2>
             }
-        });
+        };
+        // end::shrink-index-execute-listener
+
+        // Replace the empty listener by a blocking listener in test
+        final CountDownLatch latch = new CountDownLatch(1);
+        listener = new LatchedActionListener(listener, latch);
+
+        // tag::shrink-index-execute-async
+        client.indices().shrinkAsync(request, listener); // <1>
         // end::shrink-index-execute-async
+
+        assertTrue(latch.await(30L, TimeUnit.SECONDS));
     }
 
-    @SuppressWarnings("unchecked")
-    public void testSplitIndex() throws IOException {
+    @SuppressWarnings({"unchecked", "rawtypes"})
+    public void testSplitIndex() throws Exception {
         RestHighLevelClient client = highLevelClient();
 
         {
@@ -669,8 +739,8 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
         assertTrue(acknowledged);
         assertTrue(shardsAcked);
 
-        // tag::split-index-execute-async
-        client.indices().splitAsync(request, new ActionListener<ResizeResponse>() {
+        // tag::split-index-execute-listener
+        ActionListener<ResizeResponse> listener = new ActionListener<ResizeResponse>() {
             @Override
             public void onResponse(ResizeResponse resizeResponse) {
                 // <1>
@@ -680,7 +750,17 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
             public void onFailure(Exception e) {
                 // <2>
             }
-        });
+        };
+        // end::split-index-execute-listener
+
+        // Replace the empty listener by a blocking listener in test
+        final CountDownLatch latch = new CountDownLatch(1);
+        listener = new LatchedActionListener(listener, latch);
+
+        // tag::split-index-execute-async
+        client.indices().splitAsync(request,listener); // <1>
         // end::split-index-execute-async
+
+        assertTrue(latch.await(30L, TimeUnit.SECONDS));
     }
 }

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java

@@ -20,6 +20,7 @@
 package org.elasticsearch.client.documentation;
 
 import org.elasticsearch.action.ActionListener;
+import org.elasticsearch.action.LatchedActionListener;
 import org.elasticsearch.action.bulk.BulkRequest;
 import org.elasticsearch.action.bulk.BulkResponse;
 import org.elasticsearch.action.index.IndexRequest;
@@ -75,6 +76,7 @@ import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 
 import static org.elasticsearch.index.query.QueryBuilders.matchQuery;
@@ -99,8 +101,8 @@ import static org.hamcrest.Matchers.greaterThan;
  */
 public class SearchDocumentationIT extends ESRestHighLevelClientTestCase {
 
-    @SuppressWarnings({ "unused", "unchecked" })
-    public void testSearch() throws IOException {
+    @SuppressWarnings({"unused", "unchecked", "rawtypes"})
+    public void testSearch() throws Exception {
         RestHighLevelClient client = highLevelClient();
         {
             BulkRequest request = new BulkRequest();
@@ -174,8 +176,8 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase {
             SearchResponse searchResponse = client.search(searchRequest);
             // end::search-execute
 
-            // tag::search-execute-async
-            client.searchAsync(searchRequest, new ActionListener<SearchResponse>() {
+            // tag::search-execute-listener
+            ActionListener<SearchResponse> listener = new ActionListener<SearchResponse>() {
                 @Override
                 public void onResponse(SearchResponse searchResponse) {
                     // <1>
@@ -185,9 +187,19 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase {
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::search-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, latch);
+
+            // tag::search-execute-async
+            client.searchAsync(searchRequest, listener); // <1>
             // end::search-execute-async
 
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
+
             // tag::search-response-1
             RestStatus status = searchResponse.status();
             TimeValue took = searchResponse.getTook();
@@ -517,7 +529,8 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase {
         }
     }
 
-    public void testScroll() throws IOException {
+    @SuppressWarnings({"unchecked", "rawtypes"})
+    public void testScroll() throws Exception {
         RestHighLevelClient client = highLevelClient();
         {
             BulkRequest request = new BulkRequest();
@@ -587,8 +600,8 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase {
             assertEquals(0, searchResponse.getFailedShards());
             assertEquals(3L, searchResponse.getHits().getTotalHits());
 
-            // tag::search-scroll-execute-async
-            client.searchScrollAsync(scrollRequest, new ActionListener<SearchResponse>() {
+            // tag::search-scroll-execute-listener
+            ActionListener<SearchResponse> scrollListener =  new ActionListener<SearchResponse>() {
                 @Override
                 public void onResponse(SearchResponse searchResponse) {
                     // <1>
@@ -598,9 +611,19 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase {
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::search-scroll-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            scrollListener = new LatchedActionListener(scrollListener, latch);
+
+            // tag::search-scroll-execute-async
+            client.searchScrollAsync(scrollRequest, scrollListener); // <1>
             // end::search-scroll-execute-async
 
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
+
             // tag::clear-scroll-request
             ClearScrollRequest request = new ClearScrollRequest(); // <1>
             request.addScrollId(scrollId); // <2>
@@ -627,8 +650,8 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase {
             assertTrue(success);
             assertThat(released, greaterThan(0));
 
-            // tag::clear-scroll-execute-async
-            client.clearScrollAsync(request, new ActionListener<ClearScrollResponse>() {
+            // tag::clear-scroll-execute-listener
+            ActionListener<ClearScrollResponse> listener =new ActionListener<ClearScrollResponse>() {
                 @Override
                 public void onResponse(ClearScrollResponse clearScrollResponse) {
                     // <1>
@@ -638,8 +661,18 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase {
                 public void onFailure(Exception e) {
                     // <2>
                 }
-            });
+            };
+            // end::clear-scroll-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch clearScrollLatch = new CountDownLatch(1);
+            listener = new LatchedActionListener(listener, clearScrollLatch);
+
+            // tag::clear-scroll-execute-async
+            client.clearScrollAsync(request, listener); // <1>
             // end::clear-scroll-execute-async
+
+            assertTrue(clearScrollLatch.await(30L, TimeUnit.SECONDS));
         }
         {
             // tag::search-scroll-example

docs/java-rest/high-level/apis/_index.asciidoc

@@ -104,10 +104,28 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute]
 [[java-rest-high-document-index-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of an index request requires both the `IndexRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute-async]
 --------------------------------------------------
+<1> The `IndexRequest` 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 `IndexResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/apis/bulk.asciidoc

@@ -74,10 +74,28 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute]
 [[java-rest-high-document-bulk-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a bulk request requires both the `BulkRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute-async]
 --------------------------------------------------
+<1> The `BulkRequest` 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 `BulkResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument and contains a list of individual results for each
 operation that was executed. Note that one or more operations might have

docs/java-rest/high-level/apis/close_index.asciidoc

@@ -49,10 +49,28 @@ include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[close-index-execut
 [[java-rest-high-close-index-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a close index request requires both the `CloseIndexRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[close-index-execute-async]
 --------------------------------------------------
+<1> The `CloseIndexRequest` 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 `CloseIndexResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[close-index-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/apis/createindex.asciidoc → docs/java-rest/high-level/apis/create_index.asciidoc

@@ -77,10 +77,28 @@ include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[create-index-execu
 [[java-rest-high-create-index-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a create index request requires both the `CreateIndexRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[create-index-execute-async]
 --------------------------------------------------
+<1> The `CreateIndexRequest` 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 `CreateIndexResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[create-index-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/apis/delete.asciidoc

@@ -66,10 +66,28 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute]
 [[java-rest-high-document-delete-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a delete request requires both the `DeleteRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute-async]
 --------------------------------------------------
+<1> The `DeleteRequest` 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 `DeleteResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/apis/deleteindex.asciidoc → docs/java-rest/high-level/apis/delete_index.asciidoc

@@ -47,10 +47,28 @@ include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[delete-index-execu
 [[java-rest-high-delete-index-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a delete index request requires both the `DeleteIndexRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[delete-index-execute-async]
 --------------------------------------------------
+<1> The `DeleteIndexRequest` 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 `DeleteIndexResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[delete-index-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/apis/exists_alias.asciidoc

@@ -54,10 +54,28 @@ include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[exists-alias-execu
 [[java-rest-high-exists-alias-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a exists alias request requires both a `GetAliasesRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[exists-alias-execute-async]
 --------------------------------------------------
+<1> The `GetAliasesRequest` 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 the `Boolean` response looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[exists-alias-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/apis/get.asciidoc

@@ -97,10 +97,28 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-execute]
 [[java-rest-high-document-get-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a get request requires both the `GetRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-execute-async]
 --------------------------------------------------
+<1> The `GetRequest` 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 `GetResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument.
 <2> Called in case of failure. The raised exception is provided as an argument.

docs/java-rest/high-level/apis/index.asciidoc

@@ -1,12 +1,12 @@
-include::createindex.asciidoc[]
+include::create_index.asciidoc[]
 
-include::deleteindex.asciidoc[]
+include::delete_index.asciidoc[]
 
 include::open_index.asciidoc[]
 
 include::close_index.asciidoc[]
 
-include::putmapping.asciidoc[]
+include::put_mapping.asciidoc[]
 
 include::update_aliases.asciidoc[]
 

docs/java-rest/high-level/apis/open_index.asciidoc

@@ -58,10 +58,28 @@ include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[open-index-execute
 [[java-rest-high-open-index-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of an open index request requires both the `OpenIndexRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[open-index-execute-async]
 --------------------------------------------------
+<1> The `OpenIndexRequest` 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 `OpenIndexResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[open-index-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/apis/putmapping.asciidoc → docs/java-rest/high-level/apis/put_mapping.asciidoc

@@ -50,10 +50,28 @@ include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[put-mapping-execut
 [[java-rest-high-put-mapping-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a put mappings request requires both the `PutMappingRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[put-mapping-execute-async]
 --------------------------------------------------
+<1> The `PutMappingRequest` 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 `PutMappingResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[put-mapping-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/apis/scroll.asciidoc

@@ -84,10 +84,28 @@ include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-syn
 [[java-rest-high-search-scroll-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a search scroll request requires both the `SearchScrollRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-async]
 --------------------------------------------------
+<1> The `SearchScrollRequest` 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 `SearchResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument
@@ -162,10 +180,28 @@ include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-execute]
 [[java-rest-high-clear-scroll-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a clear scroll request requires both the `ClearScrollRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-execute-async]
 --------------------------------------------------
+<1> The `ClearScrollRequest` 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 `ClearScrollResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/apis/search.asciidoc

@@ -241,15 +241,29 @@ include-tagged::{doc-tests}/SearchDocumentationIT.java[search-execute]
 [[java-rest-high-document-search-async]]
 ==== Asynchronous Execution
 
-
 Executing a `SearchRequest` 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 in appropriate listeners:
+potential failures will be handled by passing the request and a listeners to the
+asynchronous search method:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/SearchDocumentationIT.java[search-execute-async]
 --------------------------------------------------
+<1> The `SearchRequest` 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 `SearchResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[search-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed.
 <2> Called when the whole `SearchRequest` fails.
 

docs/java-rest/high-level/apis/shrink_index.asciidoc

@@ -65,10 +65,28 @@ include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[shrink-index-execu
 [[java-rest-high-shrink-index-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a shrink index request requires both the `ResizeRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[shrink-index-execute-async]
 --------------------------------------------------
+<1> The `ResizeRequest` 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 `ResizeResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[shrink-index-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/apis/split_index.asciidoc

@@ -66,10 +66,28 @@ include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[split-index-execut
 [[java-rest-high-split-index-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of a split index request requires both the `ResizeRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[split-index-execute-async]
 --------------------------------------------------
+<1> The `ResizeRequest` 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 `ResizeResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[split-index-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/apis/update.asciidoc

@@ -185,10 +185,28 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-execute]
 [[java-rest-high-document-update-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of an update request requires both the `UpdateRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-execute-async]
 --------------------------------------------------
+<1> The `UpdateRequest` 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 `UpdateResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument.
 <2> Called in case of failure. The raised exception is provided as an argument.

docs/java-rest/high-level/apis/update_aliases.asciidoc

@@ -58,10 +58,28 @@ include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[update-aliases-exe
 [[java-rest-high-update-aliases-async]]
 ==== Asynchronous Execution
 
+The asynchronous execution of an update index aliases request requires both the `IndicesAliasesRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[update-aliases-execute-async]
 --------------------------------------------------
+<1> The `IndicesAliasesRequest` 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 `IndicesAliasesResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[update-aliases-execute-listener]
+--------------------------------------------------
 <1> Called when the execution is successfully completed. The response is
 provided as an argument
 <2> Called in case of failure. The raised exception is provided as an argument