Ativações de eventos programados recorrentes

Três ativações diferentes permitem programar uma automação com antecedência:

1. Time.ScheduledTimeEvent
2. Time.RecurringClockTimeScheduledEvent
3. Time.RecurringSolarTimeScheduledEvent

A primeira, Time.ScheduledTimeEvent, permite programar uma automação para começar em um único instante preciso no futuro ou de forma recorrente, com base no horário do relógio ou em um evento solar (ou seja, nascer ou pôr do sol).

Por exemplo, este gatilho inicializa a automação às 22h todos os dias:

starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(Time.ScheduledTimeEvent.clockTime(LocalTime.of(22, 0, 0, 0)))
}

Como alternativa, você pode especificar um evento de horário solar em vez de horário de relógio. O parâmetro para esse tipo de inicializador é um SolarTimeStruct que consiste em:

1. type, que é SolarTimeType.Sunrise ou SolarTimeType.Sunset.
2. offset, que permite mudar o horário de início em relação ao evento solar em qualquer período. Valores positivos introduzem um atraso após o evento solar, e valores negativos fazem com que o acionador seja ativado antes do evento solar.

O exemplo a seguir é um gatilho que inicia a automação 15 minutos antes do nascer do sol todos os dias:

starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(
    Time.ScheduledTimeEvent.solarTime(
      SolarTimeStruct(SolarTimeType.Sunrise, java.time.Duration.ofMinutes(-15))
    )
  )
}

Os dois últimos são ativadores de eventos recorrentes programados, que permitem criar automações executadas periodicamente de acordo com critérios mais específicos que podem incluir condições baseadas em tempo e calendário.

Time.RecurringClockTimeScheduledEvent permite programar uma automação com base em uma ou mais condições de data ou hora. Esse modelo inicial usa uma sintaxe semelhante à usada pelo utilitário cron do Unix para especificar a programação de uma automação recorrente.

Time.RecurringSolarTimeScheduledEvent permite programar uma automação com base no horário do nascer ou do pôr do sol, opcionalmente em combinação com uma condição baseada em calendário.

Expressões cron

Talvez você já conheça o cron, um comando usado em sistemas Unix e Linux para programar jobs recorrentes.

Os iniciadores de eventos programados recorrentes usam uma sintaxe de expressão de programação semelhante à usada pelo cron. Por isso, as expressões de programação usadas com esses iniciadores são chamadas de expressões cron.

Há vários "sabores" diferentes de cron e várias variações de sintaxe nessas implementações. As expressões de início de evento recorrente cron usam a mesma sintaxe do agendador Quartz. A sintaxe de expressão cron do Quartz é explicada na documentação do CronExpression do Quartz.

Exemplos

Confira alguns exemplos.

RecurringClockTimeScheduledEvent

Em um iniciador de RecurringClockTimeScheduledEvent, a string de expressão cron é atribuída ao campo Time.RecurringClockTimeScheduledEvent.cronExpression.

Confira um exemplo de um iniciador RecurringClockTimeScheduledEvent que inicia a automação às 20h, todas as quartas-feiras de abril:

starter<_>(structure, event = Time.RecurringClockTimeScheduledEvent) {
  parameter(Time.RecurringClockTimeScheduledEvent.cronExpression("0 0 20 ? 4 4 *"))
}

RecurringSolarTimeScheduleEvent

O inicializador RecurringSolarTimeScheduleEvent usa dois parâmetros:

1. Uma SolarTimeStruct.
2. cronExpression: um subconjunto de uma expressão cron que consiste apenas nos campos dia do mês, mês, dia da semana e ano. O horário solar determina o horário exato em que a automação vai começar. Por isso, os campos "Segundo", "Minuto" e "Hora" são omitidos.

O exemplo a seguir é um gatilho que faz uma automação começar uma hora depois do nascer do sol, todas as quartas-feiras de abril:

starter<_>(structure, event = Time.RecurringSolarTimeScheduledEvent) {
  parameter(
    Time.RecurringSolarTimeScheduledEvent.solarTime(
      TimeTrait.SolarTimeStruct(SolarTimeType.Sunrise, Duration.ofHours(1))
    )
  )
  parameter(Time.RecurringSolarTimeScheduledEvent.cronExpression("? 4 4 *"))
}