Skip to content

Commit 3e692c3

Browse files
javannajavanna
authored
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 02f2fad commit 3e692c3

File tree

26 files changed

+709
-254
lines changed

26 files changed

+709
-254
lines changed

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

+2-3
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

+55
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

+12-1
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;
@@ -1196,12 +1197,22 @@ static Request putMachineLearningJob(PutJobRequest putJobRequest) throws IOExcep
11961197
.addPathPartAsIs("anomaly_detectors")
11971198
.addPathPart(putJobRequest.getJob().getId())
11981199
.build();
1199-
12001200
Request request = new Request(HttpPut.METHOD_NAME, endpoint);
12011201
request.setEntity(createEntity(putJobRequest, REQUEST_BODY_CONTENT_TYPE));
12021202
return request;
12031203
}
12041204

1205+
static Request getMigrationAssistance(IndexUpgradeInfoRequest indexUpgradeInfoRequest) {
1206+
EndpointBuilder endpointBuilder = new EndpointBuilder()
1207+
.addPathPartAsIs("_xpack/migration/assistance")
1208+
.addCommaSeparatedPathParts(indexUpgradeInfoRequest.indices());
1209+
String endpoint = endpointBuilder.build();
1210+
Request request = new Request(HttpGet.METHOD_NAME, endpoint);
1211+
Params parameters = new Params(request);
1212+
parameters.withIndicesOptions(indexUpgradeInfoRequest.indicesOptions());
1213+
return request;
1214+
}
1215+
12051216
private static HttpEntity createEntity(ToXContent toXContent, XContentType xContentType) throws IOException {
12061217
BytesRef source = XContentHelper.toXContent(toXContent, xContentType, false).toBytesRef();
12071218
return new ByteArrayEntity(source.bytes, source.offset, source.length, createContentType(xContentType));

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

+13
Original file line numberDiff line numberDiff line change
@@ -210,6 +210,7 @@ public class RestHighLevelClient implements Closeable {
210210
private final XPackClient xPackClient = new XPackClient(this);
211211
private final WatcherClient watcherClient = new WatcherClient(this);
212212
private final LicenseClient licenseClient = new LicenseClient(this);
213+
private final MigrationClient migrationClient = new MigrationClient(this);
213214
private final MachineLearningClient machineLearningClient = new MachineLearningClient(this);
214215

215216
/**
@@ -334,6 +335,18 @@ public final XPackClient xpack() {
334335
*/
335336
public LicenseClient license() { return licenseClient; }
336337

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

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

+43
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

+18
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@
126126
import org.elasticsearch.index.rankeval.RatedRequest;
127127
import org.elasticsearch.index.rankeval.RestRankEvalAction;
128128
import org.elasticsearch.protocol.xpack.XPackInfoRequest;
129+
import org.elasticsearch.protocol.xpack.migration.IndexUpgradeInfoRequest;
129130
import org.elasticsearch.protocol.xpack.watcher.DeleteWatchRequest;
130131
import org.elasticsearch.protocol.xpack.watcher.PutWatchRequest;
131132
import org.elasticsearch.repositories.fs.FsRepository;
@@ -2552,6 +2553,23 @@ public void testXPackInfo() {
25522553
assertEquals(expectedParams, request.getParameters());
25532554
}
25542555

2556+
public void testGetMigrationAssistance() {
2557+
IndexUpgradeInfoRequest upgradeInfoRequest = new IndexUpgradeInfoRequest();
2558+
String expectedEndpoint = "/_xpack/migration/assistance";
2559+
if (randomBoolean()) {
2560+
String[] indices = randomIndicesNames(1, 5);
2561+
upgradeInfoRequest.indices(indices);
2562+
expectedEndpoint += "/" + String.join(",", indices);
2563+
}
2564+
Map<String, String> expectedParams = new HashMap<>();
2565+
setRandomIndicesOptions(upgradeInfoRequest::indicesOptions, upgradeInfoRequest::indicesOptions, expectedParams);
2566+
Request request = RequestConverters.getMigrationAssistance(upgradeInfoRequest);
2567+
assertEquals(HttpGet.METHOD_NAME, request.getMethod());
2568+
assertEquals(expectedEndpoint, request.getEndpoint());
2569+
assertNull(request.getEntity());
2570+
assertEquals(expectedParams, request.getParameters());
2571+
}
2572+
25552573
public void testXPackPutWatch() throws Exception {
25562574
PutWatchRequest putWatchRequest = new PutWatchRequest();
25572575
String watchId = randomAlphaOfLength(10);

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

+2-1
Original file line numberDiff line numberDiff line change
@@ -757,7 +757,8 @@ public void testApiNamingConventions() throws Exception {
757757
if (apiName.startsWith("xpack.") == false &&
758758
apiName.startsWith("license.") == false &&
759759
apiName.startsWith("machine_learning.") == false &&
760-
apiName.startsWith("watcher.") == false) {
760+
apiName.startsWith("watcher.") == false &&
761+
apiName.startsWith("migration.") == false) {
761762
apiNotFound.add(apiName);
762763
}
763764
}

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

+83
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

+49
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

+8
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)