Add stop rollup job support to HL REST Client (#34702)

This change adds support for stoping a rollup job to the High Level REST Client.

Relates to #29827

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

@@ -28,10 +28,14 @@ import org.elasticsearch.client.rollup.GetRollupJobRequest;
 import org.elasticsearch.client.rollup.GetRollupJobResponse;
 import org.elasticsearch.client.rollup.GetRollupCapsRequest;
 import org.elasticsearch.client.rollup.GetRollupCapsResponse;
+import org.elasticsearch.client.rollup.GetRollupJobRequest;
+import org.elasticsearch.client.rollup.GetRollupJobResponse;
 import org.elasticsearch.client.rollup.PutRollupJobRequest;
 import org.elasticsearch.client.rollup.PutRollupJobResponse;
 import org.elasticsearch.client.rollup.StartRollupJobRequest;
 import org.elasticsearch.client.rollup.StartRollupJobResponse;
+import org.elasticsearch.client.rollup.StopRollupJobRequest;
+import org.elasticsearch.client.rollup.StopRollupJobResponse;
 
 import java.io.IOException;
 import java.util.Collections;
@@ -118,6 +122,40 @@ public class RollupClient {
             listener, Collections.emptySet());
     }
 
+    /**
+     * Stop a rollup job
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/rollup-stop-job.html">
+     * the docs</a> for more.
+     * @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 StopRollupJobResponse stopRollupJob(StopRollupJobRequest request, RequestOptions options)  throws IOException {
+        return restHighLevelClient.performRequestAndParseEntity(request,
+            RollupRequestConverters::stopJob,
+            options,
+            StopRollupJobResponse::fromXContent,
+            Collections.emptySet());
+    }
+
+    /**
+     * Asynchronously stop a rollup job
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/rollup-stop-job.html">
+     * the docs</a> for more.
+     * @param request the request
+     * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @param listener the listener to be notified upon request completion
+     */
+    public void stopRollupJobAsync(StopRollupJobRequest request, RequestOptions options,
+            ActionListener<StopRollupJobResponse> listener) {
+        restHighLevelClient.performRequestAsyncAndParseEntity(request,
+            RollupRequestConverters::stopJob,
+            options,
+            StopRollupJobResponse::fromXContent,
+            listener, Collections.emptySet());
+    }
+
     /**
      * Delete a rollup job from the cluster
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/rollup-delete-job.html">

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

@@ -28,6 +28,7 @@ import org.elasticsearch.client.rollup.GetRollupIndexCapsRequest;
 import org.elasticsearch.client.rollup.GetRollupJobRequest;
 import org.elasticsearch.client.rollup.PutRollupJobRequest;
 import org.elasticsearch.client.rollup.StartRollupJobRequest;
+import org.elasticsearch.client.rollup.StopRollupJobRequest;
 
 import java.io.IOException;
 
@@ -55,8 +56,16 @@ final class RollupRequestConverters {
             .addPathPart(startRollupJobRequest.getJobId())
             .addPathPartAsIs("_start")
             .build();
-        Request request = new Request(HttpPost.METHOD_NAME, endpoint);
-        return request;
+        return new Request(HttpPost.METHOD_NAME, endpoint);
+    }
+
+    static Request stopJob(final StopRollupJobRequest stopRollupJobRequest) throws IOException {
+        String endpoint = new RequestConverters.EndpointBuilder()
+            .addPathPartAsIs("_xpack", "rollup", "job")
+            .addPathPart(stopRollupJobRequest.getJobId())
+            .addPathPartAsIs("_stop")
+            .build();
+        return new Request(HttpPost.METHOD_NAME, endpoint);
     }
 
     static Request getJob(final GetRollupJobRequest getRollupJobRequest) {

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

@@ -30,7 +30,7 @@ public class StartRollupJobResponse extends AcknowledgedResponse {
     private static final String PARSE_FIELD_NAME = "started";
 
     private static final ConstructingObjectParser<StartRollupJobResponse, Void> PARSER = AcknowledgedResponse
-            .generateParser("delete_rollup_job_response", StartRollupJobResponse::new, PARSE_FIELD_NAME);
+            .generateParser("start_rollup_job_response", StartRollupJobResponse::new, PARSE_FIELD_NAME);
 
     public StartRollupJobResponse(boolean acknowledged) {
         super(acknowledged);

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

@@ -0,0 +1,49 @@
+/*
+ * 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.rollup;
+
+import org.elasticsearch.client.Validatable;
+
+import java.util.Objects;
+
+public class StopRollupJobRequest implements Validatable {
+
+    private final String jobId;
+
+    public StopRollupJobRequest(final String jobId) {
+        this.jobId = Objects.requireNonNull(jobId, "id parameter must not be null");
+    }
+
+    public String getJobId() {
+        return jobId;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        final StopRollupJobRequest that = (StopRollupJobRequest) o;
+        return Objects.equals(jobId, that.jobId);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(jobId);
+    }
+}

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

@@ -0,0 +1,47 @@
+/*
+ * 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.rollup;
+
+import org.elasticsearch.client.core.AcknowledgedResponse;
+import org.elasticsearch.common.xcontent.ConstructingObjectParser;
+import org.elasticsearch.common.xcontent.XContentParser;
+
+import java.io.IOException;
+
+public class StopRollupJobResponse extends AcknowledgedResponse {
+
+    private static final String PARSE_FIELD_NAME = "stopped";
+
+    private static final ConstructingObjectParser<StopRollupJobResponse, Void> PARSER = AcknowledgedResponse
+            .generateParser("stop_rollup_job_response", StopRollupJobResponse::new, PARSE_FIELD_NAME);
+
+    public StopRollupJobResponse(boolean acknowledged) {
+        super(acknowledged);
+    }
+
+    public static StopRollupJobResponse fromXContent(final XContentParser parser) throws IOException {
+        return PARSER.parse(parser, null);
+    }
+
+    @Override
+    protected String getFieldName() {
+        return PARSE_FIELD_NAME;
+    }
+}

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

@@ -41,10 +41,12 @@ import org.elasticsearch.client.rollup.GetRollupJobResponse.IndexerState;
 import org.elasticsearch.client.rollup.GetRollupJobResponse.JobWrapper;
 import org.elasticsearch.client.rollup.PutRollupJobRequest;
 import org.elasticsearch.client.rollup.PutRollupJobResponse;
-import org.elasticsearch.client.rollup.StartRollupJobRequest;
-import org.elasticsearch.client.rollup.StartRollupJobResponse;
 import org.elasticsearch.client.rollup.RollableIndexCaps;
 import org.elasticsearch.client.rollup.RollupJobCaps;
+import org.elasticsearch.client.rollup.StartRollupJobRequest;
+import org.elasticsearch.client.rollup.StartRollupJobResponse;
+import org.elasticsearch.client.rollup.StopRollupJobRequest;
+import org.elasticsearch.client.rollup.StopRollupJobResponse;
 import org.elasticsearch.client.rollup.job.config.DateHistogramGroupConfig;
 import org.elasticsearch.client.rollup.job.config.GroupConfig;
 import org.elasticsearch.client.rollup.job.config.MetricConfig;
@@ -230,6 +232,11 @@ public class RollupIT extends ESRestHighLevelClientTestCase {
         assertThat(job.getStatus().getState(), either(equalTo(IndexerState.STARTED)).or(equalTo(IndexerState.INDEXING)));
         assertThat(job.getStatus().getCurrentPosition(), hasKey("date.date_histogram"));
         assertEquals(true, job.getStatus().getUpgradedDocumentId());
+
+        // stop the job
+        StopRollupJobRequest stopRequest = new StopRollupJobRequest(id);
+        StopRollupJobResponse stopResponse = execute(stopRequest, rollupClient::stopRollupJob, rollupClient::stopRollupJobAsync);
+        assertTrue(stopResponse.isAcknowledged());
     }
 
     public void testGetMissingRollupJob() throws Exception {

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

@@ -25,6 +25,7 @@ import org.apache.http.client.methods.HttpPut;
 import org.elasticsearch.client.rollup.GetRollupJobRequest;
 import org.elasticsearch.client.rollup.PutRollupJobRequest;
 import org.elasticsearch.client.rollup.StartRollupJobRequest;
+import org.elasticsearch.client.rollup.StopRollupJobRequest;
 import org.elasticsearch.client.rollup.job.config.RollupJobConfig;
 import org.elasticsearch.client.rollup.job.config.RollupJobConfigTests;
 import org.elasticsearch.test.ESTestCase;
@@ -61,6 +62,18 @@ public class RollupRequestConvertersTests extends ESTestCase {
         assertThat(request.getEntity(), nullValue());
     }
 
+    public void testStopJob() throws IOException {
+        String jobId = randomAlphaOfLength(5);
+
+        StopRollupJobRequest stopJob = new StopRollupJobRequest(jobId);
+
+        Request request = RollupRequestConverters.stopJob(stopJob);
+        assertThat(request.getEndpoint(), equalTo("/_xpack/rollup/job/" + jobId + "/_stop"));
+        assertThat(HttpPost.METHOD_NAME, equalTo(request.getMethod()));
+        assertThat(request.getParameters().keySet(), empty());
+        assertNull(request.getEntity());
+    }
+
     public void testGetJob() {
         boolean getAll = randomBoolean();
         String job = getAll ? "_all" : RequestConvertersTests.randomIndicesNames(1, 1)[0];

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

@@ -29,9 +29,7 @@ import org.elasticsearch.action.bulk.BulkResponse;
 import org.elasticsearch.action.index.IndexRequest;
 import org.elasticsearch.action.support.WriteRequest;
 import org.elasticsearch.client.ESRestHighLevelClientTestCase;
-import org.elasticsearch.client.Request;
 import org.elasticsearch.client.RequestOptions;
-import org.elasticsearch.client.Response;
 import org.elasticsearch.client.RestHighLevelClient;
 import org.elasticsearch.client.RollupClient;
 import org.elasticsearch.client.rollup.DeleteRollupJobRequest;
@@ -51,6 +49,8 @@ import org.elasticsearch.client.rollup.RollableIndexCaps;
 import org.elasticsearch.client.rollup.RollupJobCaps;
 import org.elasticsearch.client.rollup.StartRollupJobRequest;
 import org.elasticsearch.client.rollup.StartRollupJobResponse;
+import org.elasticsearch.client.rollup.StopRollupJobRequest;
+import org.elasticsearch.client.rollup.StopRollupJobResponse;
 import org.elasticsearch.client.rollup.job.config.DateHistogramGroupConfig;
 import org.elasticsearch.client.rollup.job.config.GroupConfig;
 import org.elasticsearch.client.rollup.job.config.HistogramGroupConfig;
@@ -237,59 +237,96 @@ public class RollupDocumentationIT extends ESRestHighLevelClientTestCase {
         assertTrue(latch.await(30L, TimeUnit.SECONDS));
     }
 
-
     @SuppressWarnings("unused")
     public void testStartRollupJob() throws Exception {
         testCreateRollupJob();
         RestHighLevelClient client = highLevelClient();
-
         String id = "job_1";
         // tag::rollup-start-job-request
         StartRollupJobRequest request = new StartRollupJobRequest(id); // <1>
         // end::rollup-start-job-request
-
-
         try {
             // tag::rollup-start-job-execute
             RollupClient rc = client.rollup();
             StartRollupJobResponse response = rc.startRollupJob(request, RequestOptions.DEFAULT);
             // end::rollup-start-job-execute
-
             // tag::rollup-start-job-response
             response.isAcknowledged(); // <1>
             // end::rollup-start-job-response
         } catch (Exception e) {
             // Swallow any exception, this test does not test actually cancelling.
         }
-
         // tag::rollup-start-job-execute-listener
         ActionListener<StartRollupJobResponse> listener = new ActionListener<StartRollupJobResponse>() {
             @Override
             public void onResponse(StartRollupJobResponse response) {
                  // <1>
             }
+            @Override
+            public void onFailure(Exception e) {
+                // <2>
+            }
+        };
+        // end::rollup-start-job-execute-listener
+        final CountDownLatch latch = new CountDownLatch(1);
+        listener = new LatchedActionListener<>(listener, latch);
+        // tag::rollup-start-job-execute-async
+        RollupClient rc = client.rollup();
+        rc.startRollupJobAsync(request, RequestOptions.DEFAULT, listener); // <1>
+        // end::rollup-start-job-execute-async
+        assertTrue(latch.await(30L, TimeUnit.SECONDS));
+
+        // stop job so it can correctly be deleted by the test teardown
+        rc.stopRollupJob(new StopRollupJobRequest(id), RequestOptions.DEFAULT);
+    }
+
+    @SuppressWarnings("unused")
+    public void testStopRollupJob() throws Exception {
+        testCreateRollupJob();
+        RestHighLevelClient client = highLevelClient();
+
+        String id = "job_1";
+        // tag::rollup-stop-job-request
+        StopRollupJobRequest request = new StopRollupJobRequest(id); // <1>
+        // end::rollup-stop-job-request
+
+
+        try {
+            // tag::rollup-stop-job-execute
+            RollupClient rc = client.rollup();
+            StopRollupJobResponse response = rc.stopRollupJob(request, RequestOptions.DEFAULT);
+            // end::rollup-stop-job-execute
+
+            // tag::rollup-stop-job-response
+            response.isAcknowledged(); // <1>
+            // end::rollup-stop-job-response
+        } catch (Exception e) {
+            // Swallow any exception, this test does not test actually cancelling.
+        }
+
+        // tag::rollup-stop-job-execute-listener
+        ActionListener<StopRollupJobResponse> listener = new ActionListener<StopRollupJobResponse>() {
+            @Override
+            public void onResponse(StopRollupJobResponse response) {
+                 // <1>
+            }
 
             @Override
             public void onFailure(Exception e) {
                 // <2>
             }
         };
-        // end::rollup-start-job-execute-listener
+        // end::rollup-stop-job-execute-listener
 
         final CountDownLatch latch = new CountDownLatch(1);
         listener = new LatchedActionListener<>(listener, latch);
 
-        // tag::rollup-start-job-execute-async
+        // tag::rollup-stop-job-execute-async
         RollupClient rc = client.rollup();
-        rc.startRollupJobAsync(request, RequestOptions.DEFAULT, listener); // <1>
-        // end::rollup-start-job-execute-async
+        rc.stopRollupJobAsync(request, RequestOptions.DEFAULT, listener); // <1>
+        // end::rollup-stop-job-execute-async
 
         assertTrue(latch.await(30L, TimeUnit.SECONDS));
-
-        // stop job so it can correctly be deleted by the test teardown
-        // TODO Replace this with the Rollup Stop Job API
-        Response stoptResponse = client().performRequest(new Request("POST", "/_xpack/rollup/job/" + id + "/_stop"));
-        assertEquals(RestStatus.OK.getStatus(), stoptResponse.getStatusLine().getStatusCode());
     }
 
     @SuppressWarnings("unused")

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

@@ -0,0 +1,42 @@
+/*
+ * 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.rollup;
+
+import org.elasticsearch.test.ESTestCase;
+import org.elasticsearch.test.EqualsHashCodeTestUtils;
+
+public class StopRollupJobRequestTests extends ESTestCase {
+
+    public void testConstructor() {
+        String jobId = randomAlphaOfLength(5);
+        assertEquals(jobId, new StopRollupJobRequest(jobId).getJobId());
+    }
+
+    public void testEqualsAndHash() {
+        EqualsHashCodeTestUtils.checkEqualsAndHashCode(new StopRollupJobRequest(randomAlphaOfLength(5)),
+                orig -> new StopRollupJobRequest(orig.getJobId()),
+                orig -> new StopRollupJobRequest(orig.getJobId() + "_suffix"));
+    }
+
+    public void testRequireJobId() {
+        final NullPointerException e = expectThrows(NullPointerException.class, ()-> new StopRollupJobRequest(null));
+        assertEquals("id parameter must not be null", e.getMessage());
+    }
+
+}

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

@@ -0,0 +1,51 @@
+/*
+ * 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.rollup;
+
+import org.elasticsearch.common.xcontent.XContentParser;
+import org.elasticsearch.test.AbstractXContentTestCase;
+import org.junit.Before;
+
+import java.io.IOException;
+
+public class StopRollupJobResponseTests extends AbstractXContentTestCase<StopRollupJobResponse> {
+
+    private boolean acknowledged;
+
+    @Before
+    public void setupAcknoledged() {
+        acknowledged = randomBoolean();
+    }
+
+    @Override
+    protected StopRollupJobResponse createTestInstance() {
+        return new StopRollupJobResponse(acknowledged);
+    }
+
+    @Override
+    protected  StopRollupJobResponse doParseInstance(XContentParser parser) throws IOException {
+        return StopRollupJobResponse.fromXContent(parser);
+    }
+
+    @Override
+    protected boolean supportsUnknownFields() {
+        return false;
+    }
+
+}

docs/java-rest/high-level/rollup/stop_job.asciidoc

@@ -0,0 +1,34 @@
+--
+:api: rollup-stop-job
+:request: StopRollupJobRequest
+:response: StopRollupJobResponse
+--
+
+[id="{upid}-{api}"]
+=== Stop Rollup Job API
+
+[id="{upid}-{api}-request"]
+==== Request
+
+The Stop Rollup Job API allows you to stop a job by ID.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-request]
+--------------------------------------------------
+<1> The ID of the job to stop.
+
+[id="{upid}-{api}-response"]
+==== Response
+
+The returned +{response}+ indicates if the stop command was received.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-response]
+--------------------------------------------------
+<1> Whether or not the stop job request was received.
+
+include::../execution.asciidoc[]
+
+

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

@@ -316,6 +316,7 @@ The Java High Level REST Client supports the following Rollup APIs:
 
 * <<java-rest-high-x-pack-rollup-put-job>>
 * <<{upid}-rollup-start-job>>
+* <<{upid}-rollup-stop-job>>
 * <<{upid}-rollup-delete-job>>
 * <<java-rest-high-x-pack-rollup-get-job>>
 * <<{upid}-x-pack-rollup-get-rollup-caps>>
@@ -323,6 +324,7 @@ The Java High Level REST Client supports the following Rollup APIs:
 
 include::rollup/put_job.asciidoc[]
 include::rollup/start_job.asciidoc[]
+include::rollup/stop_job.asciidoc[]
 include::rollup/delete_job.asciidoc[]
 include::rollup/get_job.asciidoc[]
 include::rollup/get_rollup_caps.asciidoc[]