[Docs] Add HLRC Async Search API documentation (#54353)

Adds documentation and a corresponding test case containing typical API usage
for the Async Search API to the High Level Rest Client.

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

@@ -0,0 +1,238 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.client.documentation;
+
+import org.elasticsearch.action.ActionListener;
+import org.elasticsearch.action.LatchedActionListener;
+import org.elasticsearch.client.ESRestHighLevelClientTestCase;
+import org.elasticsearch.client.RequestOptions;
+import org.elasticsearch.client.RestHighLevelClient;
+import org.elasticsearch.client.asyncsearch.AsyncSearchResponse;
+import org.elasticsearch.client.asyncsearch.DeleteAsyncSearchRequest;
+import org.elasticsearch.client.asyncsearch.GetAsyncSearchRequest;
+import org.elasticsearch.client.asyncsearch.SubmitAsyncSearchRequest;
+import org.elasticsearch.client.core.AcknowledgedResponse;
+import org.elasticsearch.client.indices.CreateIndexRequest;
+import org.elasticsearch.client.indices.CreateIndexResponse;
+import org.elasticsearch.common.unit.TimeValue;
+import org.elasticsearch.index.query.QueryBuilders;
+import org.elasticsearch.search.builder.SearchSourceBuilder;
+import org.junit.Before;
+
+import java.io.IOException;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Documentation for Async Search APIs in the high level java client.
+ * Code wrapped in {@code tag} and {@code end} tags is included in the docs.
+ */
+public class AsyncSearchDocumentationIT extends ESRestHighLevelClientTestCase {
+
+    @Before void setUpIndex() throws IOException {
+        CreateIndexResponse createIndexResponse = highLevelClient().indices().create(new CreateIndexRequest("my-index"),
+            RequestOptions.DEFAULT);
+        assertTrue(createIndexResponse.isAcknowledged());
+    }
+
+    public void testSubmitAsyncSearch() throws Exception {
+        RestHighLevelClient client = highLevelClient();
+
+        // tag::asyncsearch-submit-request
+        SearchSourceBuilder searchSource = new SearchSourceBuilder()
+                .query(QueryBuilders.matchAllQuery()); // <1>
+        String[] indices = new String[] { "my-index" }; // <2>
+        SubmitAsyncSearchRequest request
+                = new SubmitAsyncSearchRequest(searchSource, indices);
+        // end::asyncsearch-submit-request
+
+        // tag::asyncsearch-submit-request-arguments
+        request.setWaitForCompletionTimeout(TimeValue.timeValueSeconds(30)); // <1>
+        request.setKeepAlive(TimeValue.timeValueMinutes(15)); // <2>
+        request.setKeepOnCompletion(false); // <3>
+        // end::asyncsearch-submit-request-arguments
+
+        // tag::asyncsearch-submit-execute
+        AsyncSearchResponse response = client.asyncSearch()
+                .submit(request, RequestOptions.DEFAULT); // <1>
+        // end::asyncsearch-submit-execute
+
+        assertNotNull(response);
+        assertNull(response.getFailure());
+
+        // tag::asyncsearch-submit-response
+        response.getSearchResponse(); // <1>
+        response.getId(); // <2>
+        response.isPartial(); // <3>
+        response.isRunning(); // <4>
+        response.getStartTime(); // <5>
+        response.getExpirationTime(); // <6>
+        response.getFailure(); // <7>
+        // end::asyncsearch-submit-response
+
+
+        // tag::asyncsearch-submit-listener
+        ActionListener<AsyncSearchResponse> listener =
+            new ActionListener<AsyncSearchResponse>() {
+                @Override
+                public void onResponse(AsyncSearchResponse response) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            };
+        // end::asyncsearch-submit-listener
+
+        // Replace the empty listener by a blocking listener in test
+        final CountDownLatch latch = new CountDownLatch(1);
+        listener = new LatchedActionListener<>(listener, latch);
+
+        // tag::asyncsearch-submit-execute-async
+        client.asyncSearch()
+            .submitAsync(request, RequestOptions.DEFAULT, listener); // <1>
+        // end::asyncsearch-submit-execute-async
+
+        assertTrue(latch.await(30L, TimeUnit.SECONDS));
+    }
+
+    public void testGetAsyncSearch() throws Exception {
+        RestHighLevelClient client = highLevelClient();
+        SearchSourceBuilder searchSource = new SearchSourceBuilder().query(QueryBuilders.matchAllQuery());
+        String[] indices = new String[] { "my-index" };
+        SubmitAsyncSearchRequest submitRequest = new SubmitAsyncSearchRequest(searchSource, indices);
+        submitRequest.setKeepOnCompletion(true);
+        AsyncSearchResponse submitResponse = client.asyncSearch().submit(submitRequest, RequestOptions.DEFAULT);
+        String id = submitResponse.getId();
+
+        // tag::asyncsearch-get-request
+        GetAsyncSearchRequest request = new GetAsyncSearchRequest(id);
+        // end::asyncsearch-get-request
+
+        // tag::asyncsearch-get-request-arguments
+        request.setWaitForCompletion(TimeValue.timeValueSeconds(30)); // <1>
+        request.setKeepAlive(TimeValue.timeValueMinutes(15)); // <2>
+        // end::asyncsearch-get-request-arguments
+
+        // tag::asyncsearch-get-execute
+        AsyncSearchResponse response = client.asyncSearch()
+                .get(request, RequestOptions.DEFAULT); // <1>
+        // end::asyncsearch-get-execute
+
+        assertNotNull(response);
+        assertNull(response.getFailure());
+
+        // tag::asyncsearch-get-response
+        response.getSearchResponse(); // <1>
+        response.getId(); // <2>
+        response.isPartial(); // <3>
+        response.isRunning(); // <4>
+        response.getStartTime(); // <5>
+        response.getExpirationTime(); // <6>
+        response.getFailure(); // <7>
+        // end::asyncsearch-get-response
+
+
+        // tag::asyncsearch-get-listener
+        ActionListener<AsyncSearchResponse> listener =
+            new ActionListener<AsyncSearchResponse>() {
+                @Override
+                public void onResponse(AsyncSearchResponse response) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            };
+        // end::asyncsearch-get-listener
+
+        // Replace the empty listener by a blocking listener in test
+        final CountDownLatch latch = new CountDownLatch(1);
+        listener = new LatchedActionListener<>(listener, latch);
+
+        // tag::asyncsearch-get-execute-async
+        client.asyncSearch()
+            .getAsync(request, RequestOptions.DEFAULT, listener);  // <1>
+        // end::asyncsearch-get-execute-async
+
+        assertTrue(latch.await(30L, TimeUnit.SECONDS));
+        client.asyncSearch().delete(new DeleteAsyncSearchRequest(id), RequestOptions.DEFAULT);
+    }
+
+    @SuppressWarnings("unused")
+    public void testDeleteAsyncSearch() throws Exception {
+        RestHighLevelClient client = highLevelClient();
+        SearchSourceBuilder searchSource = new SearchSourceBuilder().query(QueryBuilders.matchAllQuery());
+        String[] indices = new String[] { "my-index" };
+        SubmitAsyncSearchRequest submitRequest = new SubmitAsyncSearchRequest(searchSource, indices);
+        submitRequest.setKeepOnCompletion(true);
+        AsyncSearchResponse submitResponse = client.asyncSearch().submit(submitRequest, RequestOptions.DEFAULT);
+        String id = submitResponse.getId();
+
+        // tag::asyncsearch-delete-request
+        DeleteAsyncSearchRequest request = new DeleteAsyncSearchRequest(id);
+        // end::asyncsearch-delete-request
+
+        // tag::asyncsearch-delete-execute
+        AcknowledgedResponse response = client.asyncSearch() // <1>
+                .delete(new DeleteAsyncSearchRequest(id),
+                        RequestOptions.DEFAULT);
+        // end::asyncsearch-delete-execute
+
+        assertNotNull(response);
+        assertTrue(response.isAcknowledged());
+
+        // tag::asyncsearch-delete-response
+        response.isAcknowledged(); // <1>
+        // end::asyncsearch-delete-response
+
+
+        // tag::asyncsearch-delete-listener
+        ActionListener<AcknowledgedResponse> listener =
+            new ActionListener<AcknowledgedResponse>() {
+                @Override
+                public void onResponse(AcknowledgedResponse response) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            };
+        // end::asyncsearch-delete-listener
+
+        // Replace the empty listener by a blocking listener in test
+        final CountDownLatch latch = new CountDownLatch(1);
+        listener = new LatchedActionListener<>(listener, latch);
+
+        // tag::asyncsearch-delete-execute-async
+        client.asyncSearch()
+            .deleteAsync(request, RequestOptions.DEFAULT, listener);  // <1>
+        // end::asyncsearch-delete-execute-async
+
+        assertTrue(latch.await(30L, TimeUnit.SECONDS));
+
+    }
+}

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

@@ -0,0 +1,68 @@
+--
+:api: asyncsearch-delete
+:request: DeleteAsyncSearchRequest
+:response: AcknowledgedResponse
+--
+
+[role="xpack"]
+[id="{upid}-{api}"]
+=== Delete Async Search API
+
+[id="{upid}-{api}-request"]
+==== Request
+
+A +{request}+ allows deleting a running asynchronous search task using
+its id. Required arguments are the `id` of a running search:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-request]
+--------------------------------------------------
+
+[id="{upid}-{api}-sync"]
+==== Synchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-execute]
+--------------------------------------------------
+<1> Execute the request and get back the response as an +{response}+ object.
+
+[id="{upid}-{api}-async"]
+==== Asynchronous Execution
+
+The asynchronous execution of a +{request}+ allows to use an 
+`ActionListener` to be called back when the submit request returns: 
+
+["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 +{response}+ looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-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
+
+[id="{upid}-{api}-response"]
+==== Response
+
+The returned +{response}+ indicates the acknowledgement of the request:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-response]
+--------------------------------------------------
+<1> `isAcknowledged` was the deletion request acknowledged or not.

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

@@ -0,0 +1,87 @@
+--
+:api: asyncsearch-get
+:request: GetAsyncSearchRequest
+:response: AsyncSearchResponse
+--
+
+[role="xpack"]
+[id="{upid}-{api}"]
+=== Get Async Search API
+
+[id="{upid}-{api}-request"]
+==== Request
+
+A +{request}+ allows to get a running asynchronous search task by
+its id. Required arguments are the `id` of a running async search:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-request]
+--------------------------------------------------
+
+==== Optional arguments
+The following arguments can optionally be provided:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-request-arguments]
+--------------------------------------------------
+<1> The minimum time that the request should wait before 
+returning a partial result (defaults to no wait).
+<2> The expiration time of the request (defaults to none).
+
+
+[id="{upid}-{api}-sync"]
+==== Synchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-execute]
+--------------------------------------------------
+<1> Execute the request and get back the response as an +{response}+ object.
+
+[id="{upid}-{api}-async"]
+==== Asynchronous Execution
+
+The asynchronous execution of a +{request}+ allows to use an 
+`ActionListener` to be called back when the submit request returns: 
+
+["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 +{response}+ looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-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
+
+[id="{upid}-{api}-response"]
+==== Response
+
+The returned +{response}+ allows to retrieve information about the executed
+ operation as follows:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-response]
+--------------------------------------------------
+<1> The `SearchResponse`, or `null` if not available yet
+<2> The id of the async search request, `null` if the response isn't stored
+<3> `true` when the response contains partial results
+<4> `true` when the search is still running
+<5> The time the response was created (millis since epoch)
+<6> The time the response expires (millis since epoch)
+<7> Get failure reasons or `null` for no failures

docs/java-rest/high-level/asyncsearch/submit.asciidoc

@@ -0,0 +1,94 @@
+--
+:api: asyncsearch-submit
+:request: SubmitAsyncSearchRequest
+:response: AsyncSearchResponse
+--
+
+[role="xpack"]
+[id="{upid}-{api}"]
+=== Submit Async Search API
+
+[id="{upid}-{api}-request"]
+==== Request
+
+A +{request}+ allows to submit an asynchronous search task to
+the cluster. Required arguments are the `SearchSourceBuilder` defining
+the search and the target indices:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-request]
+--------------------------------------------------
+<1> The definition of the search to run
+<2> The target indices for the search
+
+==== Optional arguments
+The following arguments can optionally be provided:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-request-arguments]
+--------------------------------------------------
+<1> The minimum time that the request should wait before
+returning a partial result (defaults to 1 second).
+<2> The expiration time of the request (defaults to 5 days).
+<3> Controls whether the results should be stored if the request
+completed within the provided `wait_for_completion` time (default: false)
+
+[id="{upid}-{api}-sync"]
+==== Synchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-execute]
+--------------------------------------------------
+<1> Execute the request and get back the response as an +{response}+ object.
+
+[id="{upid}-{api}-async"]
+==== Asynchronous Execution
+
+The asynchronous execution of a +{request}+ allows to use an 
+`ActionListener` to be called back when the submit request returns. Note
+that this is does not concern the execution of the submitted search request,
+which always executes asynchronously. The listener, however, waits for the
+submit request itself to come back: 
+
+["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 +{response}+ looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-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
+
+[id="{upid}-{api}-response"]
+==== Response
+
+The returned +{response}+ allows to retrieve information about the executed
+ operation as follows:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-response]
+--------------------------------------------------
+<1> The `SearchResponse`, or `null` if not available yet
+<2> The id of the async search request, `null` if the response isn't stored
+<3> `true` when the response contains partial results
+<4> `true` when the search is still running
+<5> The time the response was created (millis since epoch)
+<6> The time the response expires (millis since epoch)
+<7> Get failure reasons or `null` for no failures

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

@@ -71,6 +71,22 @@ include::search/rank-eval.asciidoc[]
 include::search/explain.asciidoc[]
 include::search/count.asciidoc[]
 
+[role="xpack"]
+== Async Search APIs
+
+:upid: {mainid}-asyncsearch
+:doc-tests-file: {doc-tests}/AsyncSearchDocumentationIT.java
+
+The Java High Level REST Client supports the following Async Search APIs:
+
+* <<{upid}-asyncsearch-submit>>
+* <<{upid}-asyncsearch-get>>
+* <<{upid}-asyncsearch-delete>>
+
+include::asyncsearch/submit.asciidoc[]
+include::asyncsearch/get.asciidoc[]
+include::asyncsearch/delete.asciidoc[]
+
 == Miscellaneous APIs
 
 The Java High Level REST Client supports the following Miscellaneous APIs:

x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.submit.json

@@ -34,7 +34,7 @@
       },
       "keep_on_completion":{
         "type":"boolean",
-        "description":"Control whether the response should be stored in the cluster if it completed within the provided [wait_for_completion] time (default: true)",
+        "description":"Control whether the response should be stored in the cluster if it completed within the provided [wait_for_completion] time (default: false)",
         "default":false
       },
       "keep_alive": {