[Docs] Document Scroll API for Java High Level REST Client

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

@@ -0,0 +1,199 @@
+/*
+ * 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.bulk.BulkRequest;
+import org.elasticsearch.action.bulk.BulkResponse;
+import org.elasticsearch.action.index.IndexRequest;
+import org.elasticsearch.action.search.ClearScrollRequest;
+import org.elasticsearch.action.search.ClearScrollResponse;
+import org.elasticsearch.action.search.SearchRequest;
+import org.elasticsearch.action.search.SearchResponse;
+import org.elasticsearch.action.search.SearchScrollRequest;
+import org.elasticsearch.action.support.WriteRequest;
+import org.elasticsearch.client.ESRestHighLevelClientTestCase;
+import org.elasticsearch.client.RestHighLevelClient;
+import org.elasticsearch.common.unit.TimeValue;
+import org.elasticsearch.common.xcontent.XContentType;
+import org.elasticsearch.rest.RestStatus;
+import org.elasticsearch.search.SearchHit;
+import org.elasticsearch.search.SearchHits;
+import org.elasticsearch.search.builder.SearchSourceBuilder;
+
+import java.io.IOException;
+import java.util.Arrays;
+import java.util.List;
+
+import static org.hamcrest.Matchers.greaterThan;
+
+/**
+ * This class is used to generate the Java High Level REST Client Search API documentation.
+ * <p>
+ * You need to wrap your code between two tags like:
+ * // tag::example[]
+ * // end::example[]
+ * <p>
+ * Where example is your tag name.
+ * <p>
+ * Then in the documentation, you can extract what is between tag and end tags with
+ * ["source","java",subs="attributes,callouts,macros"]
+ * --------------------------------------------------
+ * include-tagged::{doc-tests}/SearchDocumentationIT.java[example]
+ * --------------------------------------------------
+ */
+public class SearchDocumentationIT extends ESRestHighLevelClientTestCase {
+
+    public void testScroll() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+        {
+            BulkRequest request = new BulkRequest();
+            request.add(new IndexRequest("posts", "doc", "1")
+                    .source(XContentType.JSON, "title", "In which order are my Elasticsearch queries executed?"));
+            request.add(new IndexRequest("posts", "doc", "2")
+                    .source(XContentType.JSON, "title", "Current status and upcoming changes in Elasticsearch"));
+            request.add(new IndexRequest("posts", "doc", "3")
+                    .source(XContentType.JSON, "title", "The Future of Federated Search in Elasticsearch"));
+            request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL);
+            BulkResponse bulkResponse = client.bulk(request);
+            assertSame(bulkResponse.status(), RestStatus.OK);
+            assertFalse(bulkResponse.hasFailures());
+        }
+
+        String lastScrollId = null;
+
+        {
+            // tag::search-scroll-request
+            SearchRequest searchRequest = new SearchRequest("posts"); // <1>
+            searchRequest.scroll(TimeValue.timeValueMinutes(1L)); // <2>
+            // end::search-scroll-request
+
+            searchRequest.source(new SearchSourceBuilder().size(1));
+
+            // tag::search-response-scroll-id
+            SearchResponse searchResponse = client.search(searchRequest); // <1>
+            SearchHits searchHits = searchResponse.getHits(); // <2>
+            String scrollId = searchResponse.getScrollId(); // <3>
+            // end::search-response-scroll-id
+
+            assertEquals(0, searchResponse.getFailedShards());
+            assertEquals(3L, searchResponse.getHits().getTotalHits());
+            assertEquals(1L, searchHits.getHits().length);
+            assertNotNull(scrollId);
+            lastScrollId = scrollId;
+        }
+        {
+            String scrollId = lastScrollId;
+            // tag::search-scroll-execute
+            while (true) {
+                SearchScrollRequest scrollRequest = new SearchScrollRequest() // <1>
+                        .scroll("60s") // <2>
+                        .scrollId(scrollId);  // <3>
+
+                SearchResponse searchResponse = client.searchScroll(scrollRequest); // <4>
+                scrollId = searchResponse.getScrollId();  // <5>
+
+                SearchHit[] searchHits = searchResponse.getHits().getHits(); // <6>
+                if (searchHits != null && searchHits.length > 0) {
+                    // <7>
+                } else {
+                    // <8>
+                    break;
+                }
+            }
+            // end::search-scroll-execute
+            assertNotNull(scrollId);
+            lastScrollId = scrollId;
+        }
+        {
+            SearchScrollRequest scrollRequest = new SearchScrollRequest();
+            scrollRequest.scrollId(lastScrollId);
+
+            // tag::scroll-request-scroll
+            scrollRequest.scroll(TimeValue.timeValueSeconds(60L)); // <1>
+            scrollRequest.scroll("60s"); // <2>
+            // end::scroll-request-scroll
+
+            // tag::search-scroll-execute-sync
+            SearchResponse searchResponse = client.searchScroll(scrollRequest);
+            // end::search-scroll-execute-sync
+
+            assertEquals(0, searchResponse.getFailedShards());
+            assertEquals(3L, searchResponse.getHits().getTotalHits());
+
+            // tag::search-scroll-execute-async
+            client.searchScrollAsync(scrollRequest, new ActionListener<SearchResponse>() {
+                @Override
+                public void onResponse(SearchResponse searchResponse) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            });
+            // end::search-scroll-execute-async
+        }
+        {
+            String scrollId = lastScrollId;
+
+            // tag::clear-scroll-request
+            ClearScrollRequest request = new ClearScrollRequest(); // <1>
+            request.addScrollId(scrollId); // <2>
+            // end::clear-scroll-request
+
+            // tag::clear-scroll-add-scroll-id
+            request.addScrollId(scrollId);
+            // end::clear-scroll-add-scroll-id
+
+            List<String> scrollIds = Arrays.asList(scrollId);
+
+            // tag::clear-scroll-add-scroll-ids
+            request.setScrollIds(scrollIds);
+            // end::clear-scroll-add-scroll-ids
+
+            // tag::clear-scroll-execute
+            ClearScrollResponse response = client.clearScroll(request);
+            // end::clear-scroll-execute
+
+            // tag::clear-scroll-response
+            boolean success = response.isSucceeded(); // <1>
+            int released = response.getNumFreed(); // <2>
+            // end::clear-scroll-response
+            assertTrue(success);
+            assertThat(released, greaterThan(0));
+
+            // tag::clear-scroll-execute-async
+            client.clearScrollAsync(request, new ActionListener<ClearScrollResponse>() {
+                @Override
+                public void onResponse(ClearScrollResponse clearScrollResponse) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            });
+            // end::clear-scroll-execute-async
+        }
+    }
+}

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

@@ -12,6 +12,6 @@ The Java High Level REST Client supports the following APIs:
 * <<java-rest-high-document-bulk>>
 
 .Search APIs
-* Search API
-* Search Scroll API
-* Clear Scroll API
+* <<java-rest-high-search>>
+* <<java-rest-high-search-scroll>>
+* <<java-rest-high-clear-scroll>>

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

@@ -147,5 +147,3 @@ same index, type and id already existed:
 include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-optype]
 --------------------------------------------------
 <1> The raised exception indicates that a version conflict error was returned
-
-

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

@@ -5,5 +5,7 @@ include::get.asciidoc[]
 include::delete.asciidoc[]
 include::update.asciidoc[]
 include::bulk.asciidoc[]
+include::search.asciidoc[]
+include::scroll.asciidoc[]
 
 :doc-tests!:

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

@@ -0,0 +1,154 @@
+[[java-rest-high-search-scroll]]
+=== Search Scroll API
+
+The Scroll API can be used to retrieve a large number of results from
+a search request.
+
+In order to use scrolling, the initial search request must define
+a value for the scroll parameter:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-request]
+--------------------------------------------------
+<1> Create a new `SearchRequest`. See <<java-rest-high-search>>
+for more information on how to build `SearchRequest`.
+<2> Set the `scroll` parameter as a `TimeValue` corresponding to one minute
+
+When executing the `SearchRequest`, Elasticsearch detects the presence
+of the `scroll` parameter and keeps the search context alive during the time
+defined by the parameter.
+
+It then returns a `SearchResponse` that includes a scroll id:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[search-response-scroll-id]
+--------------------------------------------------
+<1> Execute the `SearchRequest`
+<2> Retrieve the search hits
+<3> Retrieve the scroll id
+
+This scroll id should be passed to a `SearchScrollRequest` which can be executed
+using the Search Scroll API in order to retrieve the next batch of results. Then
+the same process can be repeated over and over until no more results are returned.
+The initial search request as well as all subsequent scroll requests return a
+scroll id that can be passed to the next scroll request until results are exhausted.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute]
+--------------------------------------------------
+<1> Create a new `SearchScrollRequest`
+<2> Set the `scroll` parameter again to tell Elasticsearch to keep the search context
+alive for another minute
+<3> Set the scroll id
+<4> Execute the `SearchScrollRequest`
+<5> Retrieve the next scroll id to use in upcoming requests
+<6> Retrieve the next batch of search hits
+<7> The request returned search hits that can be processed
+<8> There are no more search hits to process, the scrolling is terminated
+
+Finally, the scroll id can be deleted using the <<java-rest-high-clear-scroll>>.
+
+==== Optional arguments
+The following argument can optionally be provided:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[scroll-request-scroll]
+--------------------------------------------------
+<1> Scroll value (ie, the time to keep alive the search context) as a `TimeValue`
+<2> Scroll value (ie, the time to keep alive the search context) as a `String`
+
+If no `scroll` value is set for the `SearchScrollRequest`, then the search context
+will expire once the initial scroll time expired (ie, the scroll time set in the
+initial search request).
+
+[[java-rest-high-search-scroll-sync]]
+==== Synchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-sync]
+--------------------------------------------------
+
+[[java-rest-high-search-scroll-async]]
+==== Asynchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[search-scroll-execute-async]
+--------------------------------------------------
+<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
+
+
+[[java-rest-high-clear-scroll]]
+=== Clear Scroll API
+
+The search contexts used by the Scroll API are automatically deleted when the scroll
+times out. But it is advised to release search contexts as soon as they are not
+necessary anymore using the Clear Scroll API.
+
+[[java-rest-high-clear-scroll-request]]
+==== Clear Scroll Request
+
+A `ClearScrollRequest` can be created as follows:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-request]
+--------------------------------------------------
+<1> Create a new `ClearScrollRequest`
+<2> Adds a scroll id to the list of scroll identifiers to clear
+
+==== Providing the scroll identifiers
+The `ClearScrollRequest` allows to clear one or more scroll identifiers in a single request.
+
+The scroll identifiers can be added to the request one by one:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-add-scroll-id]
+--------------------------------------------------
+
+Or all together using:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-add-scroll-ids]
+--------------------------------------------------
+
+[[java-rest-high-clear-scroll-sync]]
+==== Synchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-execute]
+--------------------------------------------------
+
+[[java-rest-high-clear-scroll-async]]
+==== Asynchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-execute-async]
+--------------------------------------------------
+<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
+
+[[java-rest-high-clear-scroll-response]]
+==== Clear Scroll Response
+
+The returned `ClearScrollResponse` allows to retrieve information about the released
+ search contexts:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[clear-scroll-response]
+--------------------------------------------------
+<1> Return true if the request succeeded
+<2> Return the number of released search contexts

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

@@ -0,0 +1,4 @@
+[[java-rest-high-search]]
+=== Search API
+
+To be documented.