[float]
[[api-java-put-watch]]
=== PUT Watch API

The PUT watch API either registers a new watch in {watcher} or update an
existing one. Once registered, a new document will be added to the `.watches`
index, representing the watch, and the watch trigger will immediately be
registered with the relevant trigger engine (typically the scheduler, for the
`schedule` trigger).

IMPORTANT:  Putting a watch must be done via this API only. Do not put a watch
            directly to the `.watches` index using Elasticsearch's Index API.
            When the {es} {security-features} are enabled, make sure no `write`
            privileges are granted to anyone over the `.watches` index.


The following example adds a watch with the `my-watch` id that has the following
characteristics:

* The watch schedule triggers every minute.
* The watch search input looks for any 404 HTTP responses that occurred in the
  last five minutes.
* The watch condition checks if any hits where found.
* When hits are found, the watch action sends an email to the administrator.

[source,java]
--------------------------------------------------
WatchSourceBuilder watchSourceBuilder = WatchSourceBuilders.watchBuilder();

// Set the trigger
watchSourceBuilder.trigger(TriggerBuilders.schedule(Schedules.cron("0 0/1 * * * ?")));

// Create the search request to use for the input
SearchRequest request = Requests.searchRequest("idx").source(searchSource()
        .query(boolQuery()
                .must(matchQuery("response", 404))
                .filter(rangeQuery("date").gt("{{ctx.trigger.scheduled_time}}"))
                .filter(rangeQuery("date").lt("{{ctx.execution_time}}"))
        ));

// Create the search input
SearchInput input = new SearchInput(new WatcherSearchTemplateRequest(new String[]{"idx"}, null, SearchType.DEFAULT,
    WatcherSearchTemplateRequest.DEFAULT_INDICES_OPTIONS, new BytesArray(request.source().toString())), null, null, null);

// Set the input
watchSourceBuilder.input(input);

// Set the condition
watchSourceBuilder.condition(new ScriptCondition(new Script("ctx.payload.hits.total.value > 1")));

// Create the email template to use for the action
EmailTemplate.Builder emailBuilder = EmailTemplate.builder();
emailBuilder.to("someone@domain.host.com");
emailBuilder.subject("404 recently encountered");
EmailAction.Builder emailActionBuilder = EmailAction.builder(emailBuilder.build());

// Add the action
watchSourceBuilder.addAction("email_someone", emailActionBuilder);

PutWatchResponse putWatchResponse = watcherClient.preparePutWatch("my-watch")
    .setSource(watchSourceBuilder)
    .get();
--------------------------------------------------

While the above snippet flashes out all the concrete classes that make our watch,
using the available builder classes along with static imports can significantly
simplify and compact your code:

[source,java]
--------------------------------------------------
PutWatchResponse putWatchResponse2 = watcherClient.preparePutWatch("my-watch")
        .setSource(watchBuilder()
                .trigger(schedule(cron("0 0/1 * * * ?")))
                .input(searchInput(new WatcherSearchTemplateRequest(new String[]{"idx"}, null, SearchType.DEFAULT,
                        WatcherSearchTemplateRequest.DEFAULT_INDICES_OPTIONS, searchSource()
                        .query(boolQuery()
                                .must(matchQuery("response", 404))
                                .filter(rangeQuery("date").gt("{{ctx.trigger.scheduled_time}}"))
                                .filter(rangeQuery("date").lt("{{ctx.execution_time}}"))
                        ).buildAsBytes())))
                .condition(compareCondition("ctx.payload.hits.total.value", CompareCondition.Op.GT, 1L))
                .addAction("email_someone", emailAction(EmailTemplate.builder()
                        .to("someone@domain.host.com")
                        .subject("404 recently encountered"))))
        .get();
--------------------------------------------------

* Use `TriggerBuilders` and `Schedules` classes to define the trigger
* Use `InputBuilders` class to define the input
* Use `ConditionBuilders` class to define the condition
* Use `ActionBuilders` to define the actions