HLRC: migration get assistance API

client/rest-high-level/src/main/java/org/elasticsearch/client/LicenseClient.java

@@ -48,7 +48,7 @@
  * See the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/licensing-apis.html">
  * X-Pack Licensing APIs on elastic.co</a> for more information.
  */
-public class LicenseClient {
+public final class LicenseClient {
 
     private final RestHighLevelClient restHighLevelClient;
 
@@ -98,9 +98,8 @@ public void getLicenseAsync(GetLicenseRequest request, RequestOptions options, A
             response -> new GetLicenseResponse(convertResponseToJson(response)), listener, emptySet());
     }
 
-
     /**
-     * Converts an entire response into a json sting
+     * Converts an entire response into a json string
      *
      * This is useful for responses that we don't parse on the client side, but instead work as string
      * such as in case of the license JSON

client/rest-high-level/src/main/java/org/elasticsearch/client/MigrationClient.java

@@ -0,0 +1,55 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.client;
+
+import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
+import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoResponse;
+
+import java.io.IOException;
+import java.util.Collections;
+
+/**
+ * A wrapper for the {@link RestHighLevelClient} that provides methods for
+ * accessing the Elastic License-related methods
+ * <p>
+ * See the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/migration-api.html">
+ * X-Pack Migration APIs on elastic.co</a> for more information.
+ */
+public final class MigrationClient {
+
+    private final RestHighLevelClient restHighLevelClient;
+
+    MigrationClient(RestHighLevelClient restHighLevelClient) {
+        this.restHighLevelClient = restHighLevelClient;
+    }
+
+    /**
+     * Get Migration Assistance for one or more indices
+     *
+     * @param request the request
+     * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @return the response
+     * @throws IOException in case there is a problem sending the request or parsing back the response
+     */
+    public IndexUpgradeInfoResponse getAssistance(IndexUpgradeInfoRequest request, RequestOptions options) throws IOException {
+        return restHighLevelClient.performRequestAndParseEntity(request, RequestConverters::getMigrationAssistance, options,
+            IndexUpgradeInfoResponse::fromXContent, Collections.emptySet());
+    }
+}

client/rest-high-level/src/main/java/org/elasticsearch/client/RequestConverters.java

@@ -110,6 +110,7 @@
 import org.elasticsearch.protocol.xpack.XPackUsageRequest;
 import org.elasticsearch.protocol.xpack.license.GetLicenseRequest;
 import org.elasticsearch.protocol.xpack.license.PutLicenseRequest;
+import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
 import org.elasticsearch.protocol.xpack.ml.PutJobRequest;
 import org.elasticsearch.protocol.xpack.watcher.DeleteWatchRequest;
 import org.elasticsearch.protocol.xpack.watcher.PutWatchRequest;
@@ -1190,12 +1191,22 @@ static Request putMachineLearningJob(PutJobRequest putJobRequest) throws IOExcep
             .addPathPartAsIs("anomaly_detectors")
             .addPathPart(putJobRequest.getJob().getId())
             .build();
-
         Request request = new Request(HttpPut.METHOD_NAME, endpoint);
         request.setEntity(createEntity(putJobRequest, REQUEST_BODY_CONTENT_TYPE));
         return request;
     }
 
+    static Request getMigrationAssistance(IndexUpgradeInfoRequest indexUpgradeInfoRequest) {
+        EndpointBuilder endpointBuilder = new EndpointBuilder()
+            .addPathPartAsIs("_xpack/migration/assistance")
+            .addCommaSeparatedPathParts(indexUpgradeInfoRequest.indices());
+        String endpoint = endpointBuilder.build();
+        Request request = new Request(HttpGet.METHOD_NAME, endpoint);
+        Params parameters = new Params(request);
+        parameters.withIndicesOptions(indexUpgradeInfoRequest.indicesOptions());
+        return request;
+    }
+
     private static HttpEntity createEntity(ToXContent toXContent, XContentType xContentType) throws IOException {
         BytesRef source = XContentHelper.toXContent(toXContent, xContentType, false).toBytesRef();
         return new ByteArrayEntity(source.bytes, source.offset, source.length, createContentType(xContentType));

client/rest-high-level/src/main/java/org/elasticsearch/client/RestHighLevelClient.java

@@ -210,6 +210,7 @@ public class RestHighLevelClient implements Closeable {
     private final XPackClient xPackClient = new XPackClient(this);
     private final WatcherClient watcherClient = new WatcherClient(this);
     private final LicenseClient licenseClient = new LicenseClient(this);
+    private final MigrationClient migrationClient = new MigrationClient(this);
     private final MachineLearningClient machineLearningClient = new MachineLearningClient(this);
 
     /**
@@ -334,6 +335,18 @@ public final XPackClient xpack() {
      */
     public LicenseClient license() { return licenseClient; }
 
+    /**
+     * Provides methods for accessing the Elastic Licensed Licensing APIs that
+     * are shipped with the default distribution of Elasticsearch. All of
+     * these APIs will 404 if run against the OSS distribution of Elasticsearch.
+     * <p>
+     * See the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/migration-api.html">
+     * Migration APIs on elastic.co</a> for more information.
+     */
+    public MigrationClient migration() {
+        return migrationClient;
+    }
+
     /**
      * Provides methods for accessing the Elastic Licensed Machine Learning APIs that
      * are shipped with the Elastic Stack distribution of Elasticsearch. All of

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

@@ -0,0 +1,43 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.client;
+
+import org.elasticsearch.action.admin.indices.create.CreateIndexRequest;
+import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
+import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoResponse;
+
+import java.io.IOException;
+
+public class MigrationIT extends ESRestHighLevelClientTestCase {
+
+    public void testGetAssistance() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+        {
+            IndexUpgradeInfoResponse response = client.migration().getAssistance(new IndexUpgradeInfoRequest(), RequestOptions.DEFAULT);
+            assertEquals(0, response.getActions().size());
+        }
+        {
+            client.indices().create(new CreateIndexRequest("test"), RequestOptions.DEFAULT);
+            IndexUpgradeInfoResponse response = client.migration().getAssistance(
+                new IndexUpgradeInfoRequest("test"), RequestOptions.DEFAULT);
+            assertEquals(0, response.getActions().size());
+        }
+    }
+}

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

@@ -126,6 +126,7 @@
 import org.elasticsearch.index.rankeval.RatedRequest;
 import org.elasticsearch.index.rankeval.RestRankEvalAction;
 import org.elasticsearch.protocol.xpack.XPackInfoRequest;
+import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
 import org.elasticsearch.protocol.xpack.watcher.DeleteWatchRequest;
 import org.elasticsearch.protocol.xpack.watcher.PutWatchRequest;
 import org.elasticsearch.repositories.fs.FsRepository;
@@ -2552,6 +2553,23 @@ public void testXPackInfo() {
         assertEquals(expectedParams, request.getParameters());
     }
 
+    public void testGetMigrationAssistance() {
+        IndexUpgradeInfoRequest upgradeInfoRequest = new IndexUpgradeInfoRequest();
+        String expectedEndpoint = "/_xpack/migration/assistance";
+        if (randomBoolean()) {
+            String[] indices = randomIndicesNames(1, 5);
+            upgradeInfoRequest.indices(indices);
+            expectedEndpoint += "/" + String.join(",", indices);
+        }
+        Map<String, String> expectedParams = new HashMap<>();
+        setRandomIndicesOptions(upgradeInfoRequest::indicesOptions, upgradeInfoRequest::indicesOptions, expectedParams);
+        Request request = RequestConverters.getMigrationAssistance(upgradeInfoRequest);
+        assertEquals(HttpGet.METHOD_NAME, request.getMethod());
+        assertEquals(expectedEndpoint, request.getEndpoint());
+        assertNull(request.getEntity());
+        assertEquals(expectedParams, request.getParameters());
+    }
+
     public void testXPackPutWatch() throws Exception {
         PutWatchRequest putWatchRequest = new PutWatchRequest();
         String watchId = randomAlphaOfLength(10);

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

@@ -757,7 +757,8 @@ public void testApiNamingConventions() throws Exception {
                         if (apiName.startsWith("xpack.") == false &&
                             apiName.startsWith("license.") == false &&
                             apiName.startsWith("machine_learning.") == false &&
-                            apiName.startsWith("watcher.") == false) {
+                            apiName.startsWith("watcher.") == false &&
+                            apiName.startsWith("migration.") == false) {
                             apiNotFound.add(apiName);
                         }
                     }

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

@@ -0,0 +1,83 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.client.documentation;
+
+import org.elasticsearch.action.support.IndicesOptions;
+import org.elasticsearch.client.ESRestHighLevelClientTestCase;
+import org.elasticsearch.client.RequestOptions;
+import org.elasticsearch.client.RestHighLevelClient;
+import org.elasticsearch.common.Strings;
+import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
+import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoResponse;
+import org.elasticsearch.protocol.xpack.migration.UpgradeActionRequired;
+
+import java.io.IOException;
+import java.util.Map;
+
+/**
+ * This class is used to generate the Java Migration API documentation.
+ * You need to wrap your code between two tags like:
+ * // tag::example
+ * // end::example
+ *
+ * Where example is your tag name.
+ *
+ * Then in the documentation, you can extract what is between tag and end tags with
+ * ["source","java",subs="attributes,callouts,macros"]
+ * --------------------------------------------------
+ * include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[example]
+ * --------------------------------------------------
+ *
+ * The column width of the code block is 84. If the code contains a line longer
+ * than 84, the line will be cut and a horizontal scroll bar will be displayed.
+ * (the code indentation of the tag is not included in the width)
+ */
+public class MigrationClientDocumentationIT extends ESRestHighLevelClientTestCase {
+
+    public void testGetAssistance() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+
+        // tag::get-assistance-request
+        IndexUpgradeInfoRequest request = new IndexUpgradeInfoRequest(); // <1>
+        // end::get-assistance-request
+
+        // tag::get-assistance-request-indices
+        request.indices("index1", "index2"); // <1>
+        // end::get-assistance-request-indices
+
+        request.indices(Strings.EMPTY_ARRAY);
+
+        // tag::get-assistance-request-indices-options
+        request.indicesOptions(IndicesOptions.lenientExpandOpen()); // <1>
+        // end::get-assistance-request-indices-options
+
+        // tag::get-assistance-execute
+        IndexUpgradeInfoResponse response = client.migration().getAssistance(request, RequestOptions.DEFAULT);
+        // end::get-assistance-execute
+
+        // tag::get-assistance-response
+        Map<String, UpgradeActionRequired> actions = response.getActions();
+        for (Map.Entry<String, UpgradeActionRequired> entry : actions.entrySet()) {
+            String index = entry.getKey(); // <1>
+            UpgradeActionRequired actionRequired = entry.getValue(); // <2>
+        }
+        // end::get-assistance-response
+    }
+}

docs/java-rest/high-level/migration/get-assistance.asciidoc

@@ -0,0 +1,49 @@
+[[java-rest-high-migration-get-assistance]]
+=== Migration Get Assistance
+
+[[java-rest-high-migraton-get-assistance-request]]
+==== Index Upgrade Info Request
+
+An `IndexUpgradeInfoRequest` does not require any argument:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[get-assistance-request]
+--------------------------------------------------
+<1> Create a new request instance
+
+==== Optional arguments
+The following arguments can optionally be provided:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[get-assistance-request-indices]
+--------------------------------------------------
+<1> Set the indices to the request
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[get-assistance-request-indices-options]
+--------------------------------------------------
+<1> Set the `IndicesOptions` to control how unavailable indices are resolved and
+how wildcard expressions are expanded
+
+[[java-rest-high-migration-get-assistance-execution]]
+==== Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[get-assistance-execute]
+--------------------------------------------------
+
+[[java-rest-high-migration-get-assistance-response]]
+==== Response
+
+The returned `IndexUpgradeInfoResponse` contains the actions required for each index.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[get-assistance-response]
+--------------------------------------------------
+<1> Retrieve the index
+<2> Retrieve the action required for the migration of the current index

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

@@ -198,6 +198,14 @@ The Java High Level REST Client supports the following Licensing APIs:
 include::licensing/put-license.asciidoc[]
 include::licensing/get-license.asciidoc[]
 
+== Migration APIs
+
+The Java High Level REST Client supports the following Migration APIs:
+
+* <<java-rest-high-migration-get-assistance>>
+
+include::migration/get-assistance.asciidoc[]
+
 == Watcher APIs
 
 The Java High Level REST Client supports the following Watcher APIs: