HLRC: migration api - upgrade (#34898)

Implement high level client for migration upgrade API. It should wrap
RestHighLevelClient and expose high level IndexUpgradeRequest (new),
IndexTaskResponse for submissions with wait_for_completion=false and
BulkByScrollResponse (already used) objects.

refers: #29827

docs/java-rest/high-level/migration/upgrade.asciidoc

@@ -0,0 +1,69 @@
+[[java-rest-high-migration-upgrade]]
+=== Migration Upgrade
+
+[[java-rest-high-migraton-upgrade-request]]
+==== Index Upgrade Request
+
+An `IndexUpgradeRequest` requires an index argument. Only one index at the time should be upgraded:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[upgrade-request]
+--------------------------------------------------
+<1> Create a new request instance
+
+[[java-rest-high-migration-upgrade-execution]]
+==== Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[upgrade-execute]
+--------------------------------------------------
+
+[[java-rest-high-migration-upgrade-response]]
+==== Response
+The returned `BulkByScrollResponse` contains information about the executed operation
+
+
+[[java-rest-high-migraton-async-upgrade-request]]
+==== Asynchronous Execution
+
+The asynchronous execution of a upgrade request requires both the `IndexUpgradeRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
+A typical listener for `BulkResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[upgrade-async-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
+failed while the others have been successfully executed.
+<2> Called when the whole `IndexUpgradeRequest` fails. In this case the raised
+exception is provided as an argument and no operation has been executed.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[upgrade-async-execute]
+--------------------------------------------------
+<1> The `IndexUpgradeRequest` 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.
+
+
+=== Migration Upgrade with Task API
+Submission of upgrade request task will requires the `IndexUpgradeRequest` and will return
+`IndexUpgradeSubmissionResponse`. The `IndexUpgradeSubmissionResponse` can later be use to fetch
+TaskId and query the Task API for results.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[upgrade-task-api]
+--------------------------------------------------

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

@@ -296,8 +296,10 @@ include::ml/put-filter.asciidoc[]
 The Java High Level REST Client supports the following Migration APIs:
 
 * <<java-rest-high-migration-get-assistance>>
+* <<java-rest-high-migration-upgrade>>
 
 include::migration/get-assistance.asciidoc[]
+include::migration/upgrade.asciidoc[]
 
 == Rollup APIs