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

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

3 files changed, 123 insertions, 0 deletions

diff --git a/docs/java-rest/high-level/apis/bulk.asciidoc b/docs/java-rest/high-level/apis/bulk.asciidoc
new file mode 100644
index 0000000000..07119fb4b9
--- /dev/null
+++ b/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
diff --git a/docs/java-rest/high-level/apis/index.asciidoc b/docs/java-rest/high-level/apis/index.asciidoc
index 94ed89c0fa..475b18dcf4 100644
--- a/docs/java-rest/high-level/apis/index.asciidoc
+++ b/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!:
diff --git a/docs/java-rest/high-level/apis/update.asciidoc b/docs/java-rest/high-level/apis/update.asciidoc
new file mode 100644
index 0000000000..79c4121b9f
--- /dev/null
+++ b/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
\ No newline at end of file