Skip to content

Commit 132bffd

Browse files
javannajavanna
committed
HLRC: migration get assistance API (#32744)
The request and response classes have been extracted from `IndexUpgradeInfoAction` into top-level classes, and moved to the protocol jar. The `UpgradeActionRequired` enum is also moved. Relates to #29827
1 parent 5f656d7 commit 132bffd

File tree

28 files changed

+710
-256
lines changed

28 files changed

+710
-256
lines changed

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

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@
4848
* See the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/licensing-apis.html">
4949
* X-Pack Licensing APIs on elastic.co</a> for more information.
5050
*/
51-
public class LicenseClient {
51+
public final class LicenseClient {
5252

5353
private final RestHighLevelClient restHighLevelClient;
5454

@@ -98,9 +98,8 @@ public void getLicenseAsync(GetLicenseRequest request, RequestOptions options, A
9898
response -> new GetLicenseResponse(convertResponseToJson(response)), listener, emptySet());
9999
}
100100

101-
102101
/**
103-
* Converts an entire response into a json sting
102+
* Converts an entire response into a json string
104103
*
105104
* This is useful for responses that we don't parse on the client side, but instead work as string
106105
* such as in case of the license JSON

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
/*
2+
* Licensed to Elasticsearch under one or more contributor
3+
* license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright
5+
* ownership. Elasticsearch licenses this file to you under
6+
* the Apache License, Version 2.0 (the "License"); you may
7+
* not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
package org.elasticsearch.client;
21+
22+
import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
23+
import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoResponse;
24+
25+
import java.io.IOException;
26+
import java.util.Collections;
27+
28+
/**
29+
* A wrapper for the {@link RestHighLevelClient} that provides methods for
30+
* accessing the Elastic License-related methods
31+
* <p>
32+
* See the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/migration-api.html">
33+
* X-Pack Migration APIs on elastic.co</a> for more information.
34+
*/
35+
public final class MigrationClient {
36+
37+
private final RestHighLevelClient restHighLevelClient;
38+
39+
MigrationClient(RestHighLevelClient restHighLevelClient) {
40+
this.restHighLevelClient = restHighLevelClient;
41+
}
42+
43+
/**
44+
* Get Migration Assistance for one or more indices
45+
*
46+
* @param request the request
47+
* @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
48+
* @return the response
49+
* @throws IOException in case there is a problem sending the request or parsing back the response
50+
*/
51+
public IndexUpgradeInfoResponse getAssistance(IndexUpgradeInfoRequest request, RequestOptions options) throws IOException {
52+
return restHighLevelClient.performRequestAndParseEntity(request, RequestConverters::getMigrationAssistance, options,
53+
IndexUpgradeInfoResponse::fromXContent, Collections.emptySet());
54+
}
55+
}

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

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,7 @@
110110
import org.elasticsearch.protocol.xpack.XPackUsageRequest;
111111
import org.elasticsearch.protocol.xpack.license.GetLicenseRequest;
112112
import org.elasticsearch.protocol.xpack.license.PutLicenseRequest;
113+
import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
113114
import org.elasticsearch.protocol.xpack.ml.PutJobRequest;
114115
import org.elasticsearch.protocol.xpack.watcher.DeleteWatchRequest;
115116
import org.elasticsearch.protocol.xpack.watcher.PutWatchRequest;
@@ -1207,12 +1208,22 @@ static Request putMachineLearningJob(PutJobRequest putJobRequest) throws IOExcep
12071208
.addPathPartAsIs("anomaly_detectors")
12081209
.addPathPart(putJobRequest.getJob().getId())
12091210
.build();
1210-
12111211
Request request = new Request(HttpPut.METHOD_NAME, endpoint);
12121212
request.setEntity(createEntity(putJobRequest, REQUEST_BODY_CONTENT_TYPE));
12131213
return request;
12141214
}
12151215

1216+
static Request getMigrationAssistance(IndexUpgradeInfoRequest indexUpgradeInfoRequest) {
1217+
EndpointBuilder endpointBuilder = new EndpointBuilder()
1218+
.addPathPartAsIs("_xpack/migration/assistance")
1219+
.addCommaSeparatedPathParts(indexUpgradeInfoRequest.indices());
1220+
String endpoint = endpointBuilder.build();
1221+
Request request = new Request(HttpGet.METHOD_NAME, endpoint);
1222+
Params parameters = new Params(request);
1223+
parameters.withIndicesOptions(indexUpgradeInfoRequest.indicesOptions());
1224+
return request;
1225+
}
1226+
12161227
private static HttpEntity createEntity(ToXContent toXContent, XContentType xContentType) throws IOException {
12171228
BytesRef source = XContentHelper.toXContent(toXContent, xContentType, false).toBytesRef();
12181229
return new ByteArrayEntity(source.bytes, source.offset, source.length, createContentType(xContentType));

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,6 +207,7 @@ public class RestHighLevelClient implements Closeable {
207207
private final XPackClient xPackClient = new XPackClient(this);
208208
private final WatcherClient watcherClient = new WatcherClient(this);
209209
private final LicenseClient licenseClient = new LicenseClient(this);
210+
private final MigrationClient migrationClient = new MigrationClient(this);
210211
private final MachineLearningClient machineLearningClient = new MachineLearningClient(this);
211212

212213
/**
@@ -331,6 +332,18 @@ public final XPackClient xpack() {
331332
*/
332333
public LicenseClient license() { return licenseClient; }
333334

335+
/**
336+
* Provides methods for accessing the Elastic Licensed Licensing APIs that
337+
* are shipped with the default distribution of Elasticsearch. All of
338+
* these APIs will 404 if run against the OSS distribution of Elasticsearch.
339+
* <p>
340+
* See the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/migration-api.html">
341+
* Migration APIs on elastic.co</a> for more information.
342+
*/
343+
public MigrationClient migration() {
344+
return migrationClient;
345+
}
346+
334347
/**
335348
* Provides methods for accessing the Elastic Licensed Machine Learning APIs that
336349
* are shipped with the Elastic Stack distribution of Elasticsearch. All of

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
/*
2+
* Licensed to Elasticsearch under one or more contributor
3+
* license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright
5+
* ownership. Elasticsearch licenses this file to you under
6+
* the Apache License, Version 2.0 (the "License"); you may
7+
* not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
package org.elasticsearch.client;
21+
22+
import org.elasticsearch.action.admin.indices.create.CreateIndexRequest;
23+
import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
24+
import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoResponse;
25+
26+
import java.io.IOException;
27+
28+
public class MigrationIT extends ESRestHighLevelClientTestCase {
29+
30+
public void testGetAssistance() throws IOException {
31+
RestHighLevelClient client = highLevelClient();
32+
{
33+
IndexUpgradeInfoResponse response = client.migration().getAssistance(new IndexUpgradeInfoRequest(), RequestOptions.DEFAULT);
34+
assertEquals(0, response.getActions().size());
35+
}
36+
{
37+
client.indices().create(new CreateIndexRequest("test"), RequestOptions.DEFAULT);
38+
IndexUpgradeInfoResponse response = client.migration().getAssistance(
39+
new IndexUpgradeInfoRequest("test"), RequestOptions.DEFAULT);
40+
assertEquals(0, response.getActions().size());
41+
}
42+
}
43+
}

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,7 @@
127127
import org.elasticsearch.index.rankeval.RatedRequest;
128128
import org.elasticsearch.index.rankeval.RestRankEvalAction;
129129
import org.elasticsearch.protocol.xpack.XPackInfoRequest;
130+
import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
130131
import org.elasticsearch.protocol.xpack.watcher.DeleteWatchRequest;
131132
import org.elasticsearch.protocol.xpack.watcher.PutWatchRequest;
132133
import org.elasticsearch.repositories.fs.FsRepository;
@@ -2586,6 +2587,23 @@ public void testXPackInfo() {
25862587
assertEquals(expectedParams, request.getParameters());
25872588
}
25882589

2590+
public void testGetMigrationAssistance() {
2591+
IndexUpgradeInfoRequest upgradeInfoRequest = new IndexUpgradeInfoRequest();
2592+
String expectedEndpoint = "/_xpack/migration/assistance";
2593+
if (randomBoolean()) {
2594+
String[] indices = randomIndicesNames(1, 5);
2595+
upgradeInfoRequest.indices(indices);
2596+
expectedEndpoint += "/" + String.join(",", indices);
2597+
}
2598+
Map<String, String> expectedParams = new HashMap<>();
2599+
setRandomIndicesOptions(upgradeInfoRequest::indicesOptions, upgradeInfoRequest::indicesOptions, expectedParams);
2600+
Request request = RequestConverters.getMigrationAssistance(upgradeInfoRequest);
2601+
assertEquals(HttpGet.METHOD_NAME, request.getMethod());
2602+
assertEquals(expectedEndpoint, request.getEndpoint());
2603+
assertNull(request.getEntity());
2604+
assertEquals(expectedParams, request.getParameters());
2605+
}
2606+
25892607
public void testXPackPutWatch() throws Exception {
25902608
PutWatchRequest putWatchRequest = new PutWatchRequest();
25912609
String watchId = randomAlphaOfLength(10);

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -777,7 +777,8 @@ public void testApiNamingConventions() throws Exception {
777777
if (apiName.startsWith("xpack.") == false &&
778778
apiName.startsWith("license.") == false &&
779779
apiName.startsWith("machine_learning.") == false &&
780-
apiName.startsWith("watcher.") == false) {
780+
apiName.startsWith("watcher.") == false &&
781+
apiName.startsWith("migration.") == false) {
781782
apiNotFound.add(apiName);
782783
}
783784
}

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

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
/*
2+
* Licensed to Elasticsearch under one or more contributor
3+
* license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright
5+
* ownership. Elasticsearch licenses this file to you under
6+
* the Apache License, Version 2.0 (the "License"); you may
7+
* not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
package org.elasticsearch.client.documentation;
21+
22+
import org.elasticsearch.action.support.IndicesOptions;
23+
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
24+
import org.elasticsearch.client.RequestOptions;
25+
import org.elasticsearch.client.RestHighLevelClient;
26+
import org.elasticsearch.common.Strings;
27+
import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
28+
import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoResponse;
29+
import org.elasticsearch.protocol.xpack.migration.UpgradeActionRequired;
30+
31+
import java.io.IOException;
32+
import java.util.Map;
33+
34+
/**
35+
* This class is used to generate the Java Migration API documentation.
36+
* You need to wrap your code between two tags like:
37+
* // tag::example
38+
* // end::example
39+
*
40+
* Where example is your tag name.
41+
*
42+
* Then in the documentation, you can extract what is between tag and end tags with
43+
* ["source","java",subs="attributes,callouts,macros"]
44+
* --------------------------------------------------
45+
* include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[example]
46+
* --------------------------------------------------
47+
*
48+
* The column width of the code block is 84. If the code contains a line longer
49+
* than 84, the line will be cut and a horizontal scroll bar will be displayed.
50+
* (the code indentation of the tag is not included in the width)
51+
*/
52+
public class MigrationClientDocumentationIT extends ESRestHighLevelClientTestCase {
53+
54+
public void testGetAssistance() throws IOException {
55+
RestHighLevelClient client = highLevelClient();
56+
57+
// tag::get-assistance-request
58+
IndexUpgradeInfoRequest request = new IndexUpgradeInfoRequest(); // <1>
59+
// end::get-assistance-request
60+
61+
// tag::get-assistance-request-indices
62+
request.indices("index1", "index2"); // <1>
63+
// end::get-assistance-request-indices
64+
65+
request.indices(Strings.EMPTY_ARRAY);
66+
67+
// tag::get-assistance-request-indices-options
68+
request.indicesOptions(IndicesOptions.lenientExpandOpen()); // <1>
69+
// end::get-assistance-request-indices-options
70+
71+
// tag::get-assistance-execute
72+
IndexUpgradeInfoResponse response = client.migration().getAssistance(request, RequestOptions.DEFAULT);
73+
// end::get-assistance-execute
74+
75+
// tag::get-assistance-response
76+
Map<String, UpgradeActionRequired> actions = response.getActions();
77+
for (Map.Entry<String, UpgradeActionRequired> entry : actions.entrySet()) {
78+
String index = entry.getKey(); // <1>
79+
UpgradeActionRequired actionRequired = entry.getValue(); // <2>
80+
}
81+
// end::get-assistance-response
82+
}
83+
}

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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
[[java-rest-high-migration-get-assistance]]
2+
=== Migration Get Assistance
3+
4+
[[java-rest-high-migraton-get-assistance-request]]
5+
==== Index Upgrade Info Request
6+
7+
An `IndexUpgradeInfoRequest` does not require any argument:
8+
9+
["source","java",subs="attributes,callouts,macros"]
10+
--------------------------------------------------
11+
include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[get-assistance-request]
12+
--------------------------------------------------
13+
<1> Create a new request instance
14+
15+
==== Optional arguments
16+
The following arguments can optionally be provided:
17+
18+
["source","java",subs="attributes,callouts,macros"]
19+
--------------------------------------------------
20+
include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[get-assistance-request-indices]
21+
--------------------------------------------------
22+
<1> Set the indices to the request
23+
24+
["source","java",subs="attributes,callouts,macros"]
25+
--------------------------------------------------
26+
include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[get-assistance-request-indices-options]
27+
--------------------------------------------------
28+
<1> Set the `IndicesOptions` to control how unavailable indices are resolved and
29+
how wildcard expressions are expanded
30+
31+
[[java-rest-high-migration-get-assistance-execution]]
32+
==== Execution
33+
34+
["source","java",subs="attributes,callouts,macros"]
35+
--------------------------------------------------
36+
include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[get-assistance-execute]
37+
--------------------------------------------------
38+
39+
[[java-rest-high-migration-get-assistance-response]]
40+
==== Response
41+
42+
The returned `IndexUpgradeInfoResponse` contains the actions required for each index.
43+
44+
["source","java",subs="attributes,callouts,macros"]
45+
--------------------------------------------------
46+
include-tagged::{doc-tests}/MigrationClientDocumentationIT.java[get-assistance-response]
47+
--------------------------------------------------
48+
<1> Retrieve the index
49+
<2> Retrieve the action required for the migration of the current index

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,14 @@ The Java High Level REST Client supports the following Licensing APIs:
198198
include::licensing/put-license.asciidoc[]
199199
include::licensing/get-license.asciidoc[]
200200

201+
== Migration APIs
202+
203+
The Java High Level REST Client supports the following Migration APIs:
204+
205+
* <<java-rest-high-migration-get-assistance>>
206+
207+
include::migration/get-assistance.asciidoc[]
208+
201209
== Watcher APIs
202210

203211
The Java High Level REST Client supports the following Watcher APIs:

0 commit comments

Comments
 (0)