Add documentation.

Author: jtibshirani

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

@@ -21,15 +21,23 @@
 import org.elasticsearch.action.ActionListener;
 import org.elasticsearch.action.LatchedActionListener;
 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.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.WatchStatus;
 import org.elasticsearch.common.bytes.BytesArray;
 import org.elasticsearch.common.bytes.BytesReference;
 import org.elasticsearch.common.xcontent.XContentType;
 import org.elasticsearch.protocol.xpack.watcher.DeleteWatchRequest;
 import org.elasticsearch.protocol.xpack.watcher.DeleteWatchResponse;
 import org.elasticsearch.protocol.xpack.watcher.PutWatchRequest;
 import org.elasticsearch.protocol.xpack.watcher.PutWatchResponse;
+import org.elasticsearch.rest.RestStatus;
 
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
@@ -132,4 +140,67 @@ public void onFailure(Exception e) {
         }
     }
 
+    public void testAckWatch() throws Exception {
+        RestHighLevelClient client = highLevelClient();
+
+        {
+            BytesReference watch = new BytesArray("{ \n" +
+                "  \"trigger\": { \"schedule\": { \"interval\": \"10h\" } },\n" +
+                "  \"input\": { \"simple\": { \"foo\" : \"bar\" } },\n" +
+                "  \"actions\": { \"logme\": { \"logging\": { \"text\": \"{{ctx.payload}}\" } } }\n" +
+                "}");
+            PutWatchRequest putWatchRequest = new PutWatchRequest("my_watch_id", watch, XContentType.JSON);
+            client.watcher().putWatch(putWatchRequest, RequestOptions.DEFAULT);
+
+            // TODO: use the high-level REST client here once it supports 'execute watch'.
+            Request executeWatchRequest = new Request("POST", "_xpack/watcher/watch/my_watch_id/_execute");
+            executeWatchRequest.setJsonEntity("{ \"record_execution\": true }");
+            Response executeResponse = client().performRequest(executeWatchRequest);
+            assertEquals(RestStatus.OK.getStatus(), executeResponse.getStatusLine().getStatusCode());
+        }
+
+        {
+            //tag::ack-watch-execute
+            AckWatchRequest request = new AckWatchRequest("my_watch_id", // <1>
+                "logme", "emailme"); // <2>
+            AckWatchResponse response = client.watcher().ackWatch(request, RequestOptions.DEFAULT);
+            //end::ack-watch-execute
+
+            //tag::ack-watch-response
+            WatchStatus watchStatus = response.getStatus();
+            ActionStatus actionStatus = watchStatus.actionStatus("logme"); // <1>
+            AckStatus.State ackState = actionStatus.ackStatus().state(); // <2>
+            //end::ack-watch-response
+
+            assertEquals(AckStatus.State.ACKED, ackState);
+        }
+
+        {
+            AckWatchRequest request = new AckWatchRequest("my_watch_id");
+            // tag::ack-watch-execute-listener
+            ActionListener<AckWatchResponse> listener = new ActionListener<AckWatchResponse>() {
+                @Override
+                public void onResponse(AckWatchResponse response) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            };
+            // end::ack-watch-execute-listener
+
+            // For testing, replace the empty listener by a blocking listener.
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener<>(listener, latch);
+
+            // tag::ack-watch-execute-async
+            client.watcher().ackWatchAsync(request, RequestOptions.DEFAULT, listener); // <1>
+            // end::ack-watch-execute-async
+
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
+        }
+    }
+
 }

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

@@ -298,9 +298,11 @@ The Java High Level REST Client supports the following Watcher APIs:
 
 * <<java-rest-high-x-pack-watcher-put-watch>>
 * <<java-rest-high-x-pack-watcher-delete-watch>>
+* <<java-rest-high-watcher-ack-watch>>
 
 include::watcher/put-watch.asciidoc[]
 include::watcher/delete-watch.asciidoc[]
+include::watcher/ack-watch.asciidoc[]
 
 == Graph APIs
 

docs/java-rest/high-level/watcher/ack-watch.asciidoc

@@ -0,0 +1,57 @@
+[[java-rest-high-watcher-ack-watch]]
+=== Ack Watch API
+
+[[java-rest-high-watcher-ack-watch-execution]]
+==== Execution
+
+{xpack-ref}/actions.html#actions-ack-throttle[Acknowledging a watch] enables you
+to manually throttle execution of a watch's actions. A watch can be acknowledged
+through the following request:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/WatcherDocumentationIT.java[ack-watch-execute]
+--------------------------------------------------
+<1> The ID of the watch to ack.
+<2> An optional list of IDs representing the watch actions that should be acked.
+If no action IDs are provided, then all of the watch's actions will be acked.
+
+[[java-rest-high-watcher-ack-watch-response]]
+==== Response
+
+The returned `AckWatchResponse` contains the new status of the requested watch:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/WatcherDocumentationIT.java[ack-watch-response]
+--------------------------------------------------
+<1> The status of a specific action that was acked.
+<2> The acknowledgement state of the action. If the action was successfully
+acked, this state will be equal to `AckStatus.State.ACKED`.
+
+[[java-rest-high-watcher-ack-watch-async]]
+==== Asynchronous Execution
+
+This request can be executed asynchronously:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/WatcherDocumentationIT.java[ack-watch-execute-async]
+--------------------------------------------------
+<1> The `AckWatchRequest` to execute and the `ActionListener` to use when
+the execution completes.
+
+The asynchronous method does not block and returns immediately. Once the request
+completes, the `ActionListener` is called back using the `onResponse` method
+if the execution successfully completed or using the `onFailure` method if
+it failed.
+
+A listener for `AckWatchResponse` can be constructed as follows:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/WatcherDocumentationIT.java[ack-watch-execute-listener]
+--------------------------------------------------
+<1> Called when the execution is successfully completed. The response is
+provided as an argument.
+<2> Called in case of failure. The raised exception is provided as an argument.