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

--
:api: upgrade
:request: IndexUpgradeRequest
:response: BulkByScrollResponse
:submit_response: IndexUpgradeSubmissionResponse
:doc-tests-file: {doc-tests}/MigrationClientDocumentationIT.java
--

[[java-rest-high-migration-upgrade]]
=== Migration Upgrade

[[java-rest-high-migraton-upgrade-request]]
==== Index Upgrade Request

An +{request}+ requires an index argument. Only one index at the time should be upgraded:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request]
--------------------------------------------------
<1> Create a new request instance

[[java-rest-high-migration-upgrade-execution]]
==== Execution

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-execute]
--------------------------------------------------

[[java-rest-high-migration-upgrade-response]]
==== Response
The returned +{response}+ contains information about the executed operation


[[java-rest-high-migraton-async-upgrade-request]]
==== Asynchronous Execution

The asynchronous execution of an upgrade request requires both the +{request}+
instance and an `ActionListener` instance to be passed to the asynchronous
method:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-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 +{request}+ 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-file}[{api}-async-execute]
--------------------------------------------------
<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.


=== Migration Upgrade with Task API
Submission of upgrade request task will requires the +{request}+ and will return
+{submit_response}+. The +{submit_response}+ can later be use to fetch
TaskId and query the Task API for results.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-task-api]
--------------------------------------------------