[[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's 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 integrating with Shield, a best practice is to make sure
            no `write` privileges are granted to anyone over the `.watches` API.


The following example adds an watch with the `my-watch` id that has the following qualities:

* The watch schedule triggers every minute.
* The watch search input finds any 404 HTTP responses that occurred in the past five minutes.
* The watch condition checks the search results for 404s.
* The watch action sends an email if there are any 404s.

[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(filteredQuery(matchQuery("response", 404), boolFilter()
        .must(rangeFilter("date").gt("{{ctx.trigger.scheduled_time}}"))
        .must(rangeFilter("date").lt("{{ctx.execution_time}}")))));

// Set the input
watchSourceBuilder.input(new SearchInput(request, null));

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

// 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.build());

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 putWatchResponse = watcherClient.preparePutWatch("my-watch")
    .setSource(watchBuilder()
        .trigger(schedule(cron("0 0/1 * * * ?")))
        .input(searchInput(searchRequest("idx").source(searchSource()
            .query(filteredQuery(matchQuery("response", 404), boolFilter()
                .must(rangeFilter("date").gt("{{ctx.trigger.scheduled_time}}"))
                .must(rangeFilter("date").lt("{{ctx.execution_time}}")))))))
        .condition(scriptCondition("ctx.payload.hits.total > 1"))
        .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