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

[[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]
--------------------------------------------------