[[api-java-ack-watch]]
==== Ack Watch API

<<actions-ack-throttle, Acknowledging>> a watch enables you to manually throttle
execution of the watch's actions. An action's _acknowledgement state_ is stored in the 
`_status.actions.<id>.ack.state` structure.

The current status of a watch and the state of its actions is returned with the watch
definition when you call the <<api-java-get-watch, Get Watch API>>:

[source,java]
--------------------------------------------------
GetWatchResponse getWatchResponse = watcherClient.prepareGetWatch("my-watch").get();
String state = getWatchResponse.getStatus().actionStatus("my-action").ackStatus().state();
--------------------------------------------------

The action state of a newly-created watch is `awaits_successful_execution`. When the watch
runs and its condition is met, the value changes to `ackable`. Acknowledging the action 
(using the ACK API) sets this value to `acked`.

When an action state is set to `acked`, further executions of that action are throttled
until its state is reset to `awaits_successful_execution`. This happens when the watch's
condition is checked and is not met (the condition evaluates to `false`).

The following snippet shows how to acknowledge a particular action. You specify the IDs of
the watch and the action you want to acknowledge--in this example `my-watch` and `my-action`.

[source,java]
--------------------------------------------------
AckWatchResponse ackResponse = watcherClient.prepareAckWatch("my-watch", "my-action").get();
--------------------------------------------------

As a response to this request, the status of the watch and the state of the action will be
returned in the `AckWatchResponse` object

[source,java]
--------------------------------------------------
Watch.Status status = ackResponse.getStatus();
ActionStatus actionStatus = status.actionStatus("my-action");
ActionStatus.AckStatus ackStatus = actionStatus.ackStatus();
ActionStatus.AckStatus.State ackState = ackStatus.state();
--------------------------------------------------

You can acknowledge multiple actions:

[source,java]
--------------------------------------------------
AckWatchResponse ackResponse = watcherClient.prepareAckWatch("my-watch")
  .setActionIds("action1", "action2")
  .get();
--------------------------------------------------

To acknowledge all of a watch's actions, specify `_all` as the action ID or simply omit the
actions altogether.

[source,java]
--------------------------------------------------
AckWatchResponse ackResponse = watcherClient.prepareAckWatch("my-watch").get();
--------------------------------------------------

[source,java]
--------------------------------------------------
AckWatchResponse ackResponse = watcherClient.prepareAckWatch("my-watch", "_all").get();
--------------------------------------------------