[HLRC] Add Start/Stop Watch Service APIs. (#34317)

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

@@ -19,10 +19,13 @@
 package org.elasticsearch.client;
 
 import org.elasticsearch.action.ActionListener;
+import org.elasticsearch.action.support.master.AcknowledgedResponse;
 import org.elasticsearch.client.watcher.ActivateWatchRequest;
 import org.elasticsearch.client.watcher.ActivateWatchResponse;
 import org.elasticsearch.client.watcher.AckWatchRequest;
 import org.elasticsearch.client.watcher.AckWatchResponse;
+import org.elasticsearch.client.watcher.StartWatchServiceRequest;
+import org.elasticsearch.client.watcher.StopWatchServiceRequest;
 import org.elasticsearch.protocol.xpack.watcher.DeleteWatchRequest;
 import org.elasticsearch.protocol.xpack.watcher.DeleteWatchResponse;
 import org.elasticsearch.protocol.xpack.watcher.PutWatchRequest;
@@ -41,6 +44,59 @@ public final class WatcherClient {
         this.restHighLevelClient = restHighLevelClient;
     }
 
+    /**
+     * Start the watch service
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-start.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 AcknowledgedResponse startWatchService(StartWatchServiceRequest request, RequestOptions options) throws IOException {
+        return restHighLevelClient.performRequestAndParseEntity(
+                request, WatcherRequestConverters::startWatchService, options, AcknowledgedResponse::fromXContent, emptySet());
+    }
+
+    /**
+     * Asynchronously start the watch service
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-start.html">
+     * the docs</a> for more.
+     * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     */
+    public void startWatchServiceAsync(StartWatchServiceRequest request, RequestOptions options,
+            ActionListener<AcknowledgedResponse> listener) {
+        restHighLevelClient.performRequestAsyncAndParseEntity(
+                request, WatcherRequestConverters::startWatchService, options, AcknowledgedResponse::fromXContent, listener, emptySet());
+    }
+
+    /**
+     * Stop the watch service
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-start.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 AcknowledgedResponse stopWatchService(StopWatchServiceRequest request, RequestOptions options) throws IOException {
+        return restHighLevelClient.performRequestAndParseEntity(
+                request, WatcherRequestConverters::stopWatchService, options, AcknowledgedResponse::fromXContent, emptySet());
+    }
+
+    /**
+     * Asynchronously stop the watch service
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-start.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
+     */
+    public void stopWatchServiceAsync(StopWatchServiceRequest request, RequestOptions options,
+            ActionListener<AcknowledgedResponse> listener) {
+        restHighLevelClient.performRequestAsyncAndParseEntity(
+                request, WatcherRequestConverters::stopWatchService, options, AcknowledgedResponse::fromXContent, listener, emptySet());
+    }
+
     /**
      * Put a watch into the cluster
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-put-watch.html">

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

@@ -20,17 +20,40 @@
 package org.elasticsearch.client;
 
 import org.apache.http.client.methods.HttpDelete;
+import org.apache.http.client.methods.HttpPost;
 import org.apache.http.client.methods.HttpPut;
 import org.apache.http.entity.ByteArrayEntity;
 import org.apache.http.entity.ContentType;
 import org.elasticsearch.client.watcher.ActivateWatchRequest;
 import org.elasticsearch.client.watcher.AckWatchRequest;
+import org.elasticsearch.client.watcher.StartWatchServiceRequest;
+import org.elasticsearch.client.watcher.StopWatchServiceRequest;
 import org.elasticsearch.common.bytes.BytesReference;
 import org.elasticsearch.protocol.xpack.watcher.DeleteWatchRequest;
 import org.elasticsearch.protocol.xpack.watcher.PutWatchRequest;
 
 public class WatcherRequestConverters {
 
+    static Request startWatchService(StartWatchServiceRequest startWatchServiceRequest) {
+        String endpoint = new RequestConverters.EndpointBuilder()
+                .addPathPartAsIs("_xpack")
+                .addPathPartAsIs("watcher")
+                .addPathPartAsIs("_start")
+                .build();
+
+        return new Request(HttpPost.METHOD_NAME, endpoint);
+    }
+
+    static Request stopWatchService(StopWatchServiceRequest stopWatchServiceRequest) {
+        String endpoint = new RequestConverters.EndpointBuilder()
+                .addPathPartAsIs("_xpack")
+                .addPathPartAsIs("watcher")
+                .addPathPartAsIs("_stop")
+                .build();
+
+        return new Request(HttpPost.METHOD_NAME, endpoint);
+    }
+
     static Request putWatch(PutWatchRequest putWatchRequest) {
         String endpoint = new RequestConverters.EndpointBuilder()
             .addPathPartAsIs("_xpack")

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

@@ -0,0 +1,26 @@
+/*
+ * 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.watcher;
+
+import org.elasticsearch.client.Validatable;
+
+public class StartWatchServiceRequest implements Validatable {
+
+}

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

@@ -0,0 +1,26 @@
+/*
+ * 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.watcher;
+
+import org.elasticsearch.client.Validatable;
+
+public class StopWatchServiceRequest implements Validatable {
+
+}

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

@@ -19,12 +19,15 @@
 package org.elasticsearch.client;
 
 import org.elasticsearch.ElasticsearchStatusException;
-import org.elasticsearch.client.watcher.ActivateWatchRequest;
-import org.elasticsearch.client.watcher.ActivateWatchResponse;
+import org.elasticsearch.action.support.master.AcknowledgedResponse;
 import org.elasticsearch.client.watcher.AckWatchRequest;
 import org.elasticsearch.client.watcher.AckWatchResponse;
 import org.elasticsearch.client.watcher.ActionStatus;
 import org.elasticsearch.client.watcher.ActionStatus.AckStatus;
+import org.elasticsearch.client.watcher.ActivateWatchRequest;
+import org.elasticsearch.client.watcher.ActivateWatchResponse;
+import org.elasticsearch.client.watcher.StartWatchServiceRequest;
+import org.elasticsearch.client.watcher.StopWatchServiceRequest;
 import org.elasticsearch.common.bytes.BytesArray;
 import org.elasticsearch.common.bytes.BytesReference;
 import org.elasticsearch.common.xcontent.XContentType;
@@ -39,6 +42,18 @@ import static org.hamcrest.Matchers.lessThan;
 
 public class WatcherIT extends ESRestHighLevelClientTestCase {
 
+    public void testStartWatchService() throws Exception {
+        AcknowledgedResponse response =
+                highLevelClient().watcher().startWatchService(new StartWatchServiceRequest(), RequestOptions.DEFAULT);
+        assertTrue(response.isAcknowledged());
+    }
+
+    public void testStopWatchService() throws Exception {
+        AcknowledgedResponse response =
+                highLevelClient().watcher().stopWatchService(new StopWatchServiceRequest(), RequestOptions.DEFAULT);
+        assertTrue(response.isAcknowledged());
+    }
+
     public void testPutWatch() throws Exception {
         String watchId = randomAlphaOfLength(10);
         PutWatchResponse putWatchResponse = createWatch(watchId);

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

@@ -20,9 +20,12 @@
 package org.elasticsearch.client;
 
 import org.apache.http.client.methods.HttpDelete;
+import org.apache.http.client.methods.HttpPost;
 import org.apache.http.client.methods.HttpPut;
 import org.elasticsearch.client.watcher.ActivateWatchRequest;
 import org.elasticsearch.client.watcher.AckWatchRequest;
+import org.elasticsearch.client.watcher.StartWatchServiceRequest;
+import org.elasticsearch.client.watcher.StopWatchServiceRequest;
 import org.elasticsearch.common.bytes.BytesArray;
 import org.elasticsearch.common.xcontent.XContentType;
 import org.elasticsearch.protocol.xpack.watcher.DeleteWatchRequest;
@@ -39,6 +42,18 @@ import static org.hamcrest.Matchers.nullValue;
 
 public class WatcherRequestConvertersTests extends ESTestCase {
 
+    public void testStartWatchService() {
+        Request request = WatcherRequestConverters.startWatchService(new StartWatchServiceRequest());
+        assertEquals(HttpPost.METHOD_NAME, request.getMethod());
+        assertEquals("/_xpack/watcher/_start", request.getEndpoint());
+    }
+
+    public void testStopWatchService() {
+        Request request = WatcherRequestConverters.stopWatchService(new StopWatchServiceRequest());
+        assertEquals(HttpPost.METHOD_NAME, request.getMethod());
+        assertEquals("/_xpack/watcher/_stop", request.getEndpoint());
+    }
+
     public void testPutWatch() throws Exception {
         PutWatchRequest putWatchRequest = new PutWatchRequest();
         String watchId = randomAlphaOfLength(10);

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

@@ -20,6 +20,7 @@ package org.elasticsearch.client.documentation;
 
 import org.elasticsearch.action.ActionListener;
 import org.elasticsearch.action.LatchedActionListener;
+import org.elasticsearch.action.support.master.AcknowledgedResponse;
 import org.elasticsearch.client.ESRestHighLevelClientTestCase;
 import org.elasticsearch.client.Request;
 import org.elasticsearch.client.RequestOptions;
@@ -31,6 +32,8 @@ import org.elasticsearch.client.watcher.AckWatchRequest;
 import org.elasticsearch.client.watcher.AckWatchResponse;
 import org.elasticsearch.client.watcher.ActionStatus;
 import org.elasticsearch.client.watcher.ActionStatus.AckStatus;
+import org.elasticsearch.client.watcher.StartWatchServiceRequest;
+import org.elasticsearch.client.watcher.StopWatchServiceRequest;
 import org.elasticsearch.client.watcher.WatchStatus;
 import org.elasticsearch.common.bytes.BytesArray;
 import org.elasticsearch.common.bytes.BytesReference;
@@ -46,6 +49,92 @@ import java.util.concurrent.TimeUnit;
 
 public class WatcherDocumentationIT extends ESRestHighLevelClientTestCase {
 
+    public void testStartStopWatchService() throws Exception {
+        RestHighLevelClient client = highLevelClient();
+
+        {
+            //tag::start-watch-service-request
+            StartWatchServiceRequest request = new StartWatchServiceRequest();
+            //end::start-watch-service-request
+
+            //tag::start-watch-service-execute
+            AcknowledgedResponse response = client.watcher().startWatchService(request, RequestOptions.DEFAULT);
+            //end::start-watch-service-execute
+
+            //tag::start-watch-service-response
+            boolean isAcknowledged = response.isAcknowledged(); // <1>
+            //end::start-watch-service-response
+        }
+
+        {
+            //tag::stop-watch-service-request
+            StopWatchServiceRequest request = new StopWatchServiceRequest();
+            //end::stop-watch-service-request
+
+            //tag::stop-watch-service-execute
+            AcknowledgedResponse response = client.watcher().stopWatchService(request, RequestOptions.DEFAULT);
+            //end::stop-watch-service-execute
+
+            //tag::stop-watch-service-response
+            boolean isAcknowledged = response.isAcknowledged(); // <1>
+            //end::stop-watch-service-response
+        }
+
+        {
+            StartWatchServiceRequest request = new StartWatchServiceRequest();
+
+            // tag::start-watch-service-execute-listener
+            ActionListener<AcknowledgedResponse> listener = new ActionListener<AcknowledgedResponse>() {
+                @Override
+                public void onResponse(AcknowledgedResponse response) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            };
+            // end::start-watch-service-execute-listener
+            
+            CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener<>(listener, latch);
+
+            // tag::start-watch-service-execute-async
+            client.watcher().startWatchServiceAsync(request, RequestOptions.DEFAULT, listener); // <1>
+            // end::start-watch-service-execute-async
+
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
+        }
+
+        {
+            StopWatchServiceRequest request = new StopWatchServiceRequest();
+
+            // tag::stop-watch-service-execute-listener
+            ActionListener<AcknowledgedResponse> listener = new ActionListener<AcknowledgedResponse>() {
+                @Override
+                public void onResponse(AcknowledgedResponse response) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            };
+            // end::stop-watch-service-execute-listener
+
+            CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener<>(listener, latch);
+
+            // tag::stop-watch-service-execute-async
+            client.watcher().stopWatchServiceAsync(request, RequestOptions.DEFAULT, listener); // <1>
+            // end::stop-watch-service-execute-async
+
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
+        }
+    }
+
     public void testWatcher() throws Exception {
         RestHighLevelClient client = highLevelClient();
 

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

@@ -335,11 +335,15 @@ include::security/delete-role-mapping.asciidoc[]
 
 The Java High Level REST Client supports the following Watcher APIs:
 
+* <<java-rest-high-watcher-start-watch-service>>
+* <<java-rest-high-watcher-stop-watch-service>>
 * <<java-rest-high-x-pack-watcher-put-watch>>
 * <<java-rest-high-x-pack-watcher-delete-watch>>
 * <<{upid}-ack-watch>>
 * <<{upid}-activate-watch>>
 
+include::watcher/start-watch-service.asciidoc[]
+include::watcher/stop-watch-service.asciidoc[]
 include::watcher/put-watch.asciidoc[]
 include::watcher/delete-watch.asciidoc[]
 include::watcher/ack-watch.asciidoc[]

docs/java-rest/high-level/watcher/start-watch-service.asciidoc

@@ -0,0 +1,33 @@
+--
+:api: start-watch-service
+:request: StartWatchServiceRequest
+:response: StartWatchServiceResponse
+--
+[id="{upid}-{api}"]
+=== Start Watch Service API
+
+[id="{upid}-{api}-request"]
+==== Execution
+
+{xpack-ref}/watcher-api-start.html[Start watcher] enables you
+to manually start the watch service. Submit the following request
+to start the watch service:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-request]
+--------------------------------------------------
+
+[id="{upid}-{api}-response"]
+==== Response
+
+The returned `AcknowledgeResponse` contains a value on whether or not the request
+was received:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-response]
+--------------------------------------------------
+<1> A boolean value of `true` if successfully received, `false` otherwise.
+
+include::../execution.asciidoc[]

docs/java-rest/high-level/watcher/stop-watch-service.asciidoc

@@ -0,0 +1,33 @@
+--
+:api: stop-watch-service
+:request: StopWatchServiceRequest
+:response: StopWatchServiceResponse
+--
+[id="{upid}-{api}"]
+=== Stop Watch Service API
+
+[[java-rest-high-watcher-stop-watch-service-execution]]
+==== Execution
+
+{xpack-ref}/watcher-api-stop.html[Stop watcher] enables you
+to manually stop the watch service. Submit the following request
+to stop the watch service:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-request]
+--------------------------------------------------
+
+[[java-rest-high-watcher-stop-watch-service-response]]
+==== Response
+
+The returned `AcknowledgeResponse` contains a value on whether or not the request
+was received:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-response]
+--------------------------------------------------
+<1> A boolean value of `true` if successfully received, `false` otherwise.
+
+include::../execution.asciidoc[]