[Docs] Document Bulk API for Java High Level REST Client (#25532)

This commit adds documentation for Java High Level REST Client's Bulk API.

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

@@ -23,13 +23,20 @@ import org.elasticsearch.ElasticsearchException;
 import org.elasticsearch.action.ActionListener;
 import org.elasticsearch.action.DocWriteRequest;
 import org.elasticsearch.action.DocWriteResponse;
+import org.elasticsearch.action.bulk.BulkItemResponse;
+import org.elasticsearch.action.bulk.BulkRequest;
+import org.elasticsearch.action.bulk.BulkResponse;
 import org.elasticsearch.action.delete.DeleteRequest;
 import org.elasticsearch.action.delete.DeleteResponse;
 import org.elasticsearch.action.index.IndexRequest;
 import org.elasticsearch.action.index.IndexResponse;
+import org.elasticsearch.action.support.ActiveShardCount;
 import org.elasticsearch.action.support.WriteRequest;
 import org.elasticsearch.action.support.replication.ReplicationResponse;
+import org.elasticsearch.action.update.UpdateRequest;
+import org.elasticsearch.action.update.UpdateResponse;
 import org.elasticsearch.client.ESRestHighLevelClientTestCase;
+import org.elasticsearch.client.Requests;
 import org.elasticsearch.client.RestHighLevelClient;
 import org.elasticsearch.common.unit.TimeValue;
 import org.elasticsearch.common.xcontent.XContentBuilder;
@@ -318,4 +325,96 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
             // end::delete-conflict
         }
     }
+
+    public void testBulk() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+        {
+            // tag::bulk-request
+            BulkRequest request = new BulkRequest(); // <1>
+            request.add(new IndexRequest("index", "type", "0")  // <2>
+                    .source(XContentType.JSON,"field", "foo"));
+            request.add(new IndexRequest("index", "type", "1")  // <3>
+                    .source(XContentType.JSON,"field", "bar"));
+            request.add(new IndexRequest("index", "type", "2")  // <4>
+                    .source(XContentType.JSON,"field", "baz"));
+            // end::bulk-request
+            // tag::bulk-execute
+            BulkResponse bulkResponse = client.bulk(request);
+            // end::bulk-execute
+            assertSame(bulkResponse.status(), RestStatus.OK);
+            assertFalse(bulkResponse.hasFailures());
+        }
+        {
+            // tag::bulk-request-with-mixed-operations
+            BulkRequest request = new BulkRequest();
+            request.add(new DeleteRequest("index", "type", "2")); // <1>
+            request.add(new UpdateRequest("index", "type", "1") // <2>
+                    .doc(XContentType.JSON,"other", "test"));
+            request.add(new IndexRequest("index", "type", "4")  // <3>
+                    .source(XContentType.JSON,"field", "baz"));
+            // end::bulk-request-with-mixed-operations
+            BulkResponse bulkResponse = client.bulk(request);
+            assertSame(bulkResponse.status(), RestStatus.OK);
+            assertFalse(bulkResponse.hasFailures());
+
+            // tag::bulk-response
+            for (BulkItemResponse bulkItemResponse : bulkResponse) { // <1>
+                DocWriteResponse itemResponse = bulkItemResponse.getResponse(); // <2>
+
+                if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.INDEX
+                        || bulkItemResponse.getOpType() == DocWriteRequest.OpType.CREATE) { // <3>
+                    IndexResponse indexResponse = (IndexResponse)itemResponse;
+
+                } else if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.UPDATE) { // <4>
+                    UpdateResponse updateResponse = (UpdateResponse)itemResponse;
+
+                } else if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.DELETE) { // <5>
+                    DeleteResponse deleteResponse = (DeleteResponse) itemResponse;
+                }
+            }
+            // end::bulk-response
+            // tag::bulk-has-failures
+            if (bulkResponse.hasFailures()) { // <1>
+
+            }
+            // end::bulk-has-failures
+            // tag::bulk-errors
+            for (BulkItemResponse bulkItemResponse : bulkResponse) {
+                if (bulkItemResponse.isFailed()) { // <1>
+                    BulkItemResponse.Failure failure = bulkItemResponse.getFailure(); // <2>
+
+                }
+            }
+            // end::bulk-errors
+        }
+        {
+            BulkRequest request = new BulkRequest();
+            // tag::bulk-request-timeout
+            request.timeout(TimeValue.timeValueMinutes(2)); // <1>
+            request.timeout("2m"); // <2>
+            // end::bulk-request-timeout
+            // tag::bulk-request-refresh
+            request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); // <1>
+            request.setRefreshPolicy("wait_for");                            // <2>
+            // end::bulk-request-refresh
+            // tag::bulk-request-active-shards
+            request.waitForActiveShards(2); // <1>
+            request.waitForActiveShards(ActiveShardCount.ALL); // <2>
+            // end::bulk-request-active-shards
+
+            // tag::bulk-execute-async
+            client.bulkAsync(request, new ActionListener<BulkResponse>() {
+                @Override
+                public void onResponse(BulkResponse bulkResponse) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            });
+            // end::bulk-execute-async
+        }
+    }
 }

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

@@ -10,7 +10,7 @@ The Java High Level REST Client supports the following APIs:
 
 * Update API
 
-* Bulk API
+* <<java-rest-high-document-bulk>>
 
 * Search API
 

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

@@ -0,0 +1,117 @@
+[[java-rest-high-document-bulk]]
+=== Bulk API
+
+[[java-rest-high-document-bulk-request]]
+==== Bulk Request
+
+A `BulkRequest` can be used to execute multiple index, update and/or delete
+operations using a single request.
+
+It requires at least one operation to be added to the Bulk request:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request]
+--------------------------------------------------
+<1> Creates the `BulkRequest`
+<2> Adds a first `IndexRequest` to the Bulk request. See <<java-rest-high-document-index>>
+for more information on how to build `IndexRequest`.
+<3> Adds a second `IndexRequest`
+<4> Adds a third `IndexRequest`
+
+WARNING: The Bulk API supports only documents encoded in JSON or SMILE. Providing documents
+ in any other format will result in an error.
+
+And different operation types can be added to the same `BulkRequest`:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-with-mixed-operations]
+--------------------------------------------------
+<1> Adds a `DeleteRequest` to the `BulkRequest`. See <<java-rest-high-document-delete>>
+for more information on how to build `DeleteRequest`.
+<2> Adds an `UpdateRequest` to the `BulkRequest`. See <<java-rest-high-document-update>>
+for more information on how to build `UpdateRequest`.
+<3> Adds an `IndexRequest` using the SMILE format
+
+==== Optional arguments
+The following arguments can optionally be provided:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-timeout]
+--------------------------------------------------
+<1> Timeout to wait for the bulk request to be performed as a `TimeValue`
+<2> Timeout to wait for the bulk request to be performed as a `String`
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-refresh]
+--------------------------------------------------
+<1> Refresh policy as a `WriteRequest.RefreshPolicy` instance
+<2> Refresh policy as a `String`
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-active-shards]
+--------------------------------------------------
+<1> Sets the number of shard copies that must be active before proceeding with
+the index/update/delete operations.
+<2> Number of shard copies provided as a `ActiveShardCount`: can be `ActiveShardCount.ALL`,
+`ActiveShardCount.ONE` or `ActiveShardCount.DEFAULT` (default)
+
+
+[[java-rest-high-document-bulk-sync]]
+==== Synchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute]
+--------------------------------------------------
+
+[[java-rest-high-document-bulk-async]]
+==== Asynchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute-async]
+--------------------------------------------------
+<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
+failed while the others have been successfully executed.
+<2> Called when the whole `BulkRequest` fails. In this case the raised
+exception is provided as an argument and no operation has been executed.
+
+[[java-rest-high-document-bulk-response]]
+==== Bulk Response
+
+The returned `BulkResponse` contains information about the executed operations and
+ allows to iterate over each result as follows:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-response]
+--------------------------------------------------
+<1> Iterate over the results of all operations
+<2> Retrieve the response of the operation (successful or not), can be `IndexResponse`,
+`UpdateResponse` or `DeleteResponse` which can all be seen as `DocWriteResponse` instances
+<3> Handle the response of an index operation
+<4> Handle the response of a update operation
+<5> Handle the response of a delete operation
+
+The Bulk response provides a method to quickly check if one or more operation has failed:
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-has-failures]
+--------------------------------------------------
+<1> This method returns `true` if at least one operation failed
+
+In such situation it is necessary to iterate over all operation results in order to check
+ if the operation failed, and if so, retrieve the corresponding failure:
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-errors]
+--------------------------------------------------
+<1> Indicate if a given operation failed
+<2> Retrieve the failure of the failed operation

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

@@ -1,6 +1,8 @@
 :doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation
 
 include::_index.asciidoc[]
+include::update.asciidoc[]
 include::delete.asciidoc[]
+include::bulk.asciidoc[]
 
 :doc-tests!:

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

@@ -0,0 +1,4 @@
+[[java-rest-high-document-update]]
+=== Update API
+
+See https://github.com/elastic/elasticsearch/pull/25536