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, esta ativação inicia a automação às 22h todos os dias:

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

Como alternativa, é possível especificar um evento de hora solar em vez de hora do relógio. O parâmetro para esse tipo de ativação é 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 por qualquer período. Valores positivos introduzem um atraso após o evento solar, e valores negativos fazem com que a ativação ocorra antes do evento solar.

O exemplo a seguir é uma ativação 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))
    )
  )
}

As outras duas são ativações de eventos programados recorrentes, que permitem criar automações que são executadas periodicamente de acordo com critérios mais específicos, que podem incluir condições baseadas em tempo e na agenda.

Time.RecurringClockTimeScheduledEvent permite programar uma automação com base em uma ou mais condições de hora ou data. Esse inicializador 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 na agenda.

cron expressão

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 "tipos" diferentes de cron e várias variações de sintaxe nessas implementações. As expressões de inicialização de eventos programados recorrentes cron usam a mesma sintaxe do programador Quartz. A sintaxe da expressão Quartz cron é explicada na documentação do CronExpression do Quartz.

Exemplos

Confira alguns exemplos para ilustrar.

RecurringClockTimeScheduledEvent

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

Veja um exemplo de ativação 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 será iniciada. Portanto, os campos de segundo, minuto e hora são omitidos.

O exemplo a seguir é uma ativação que inicia uma automação uma hora após o 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 *"))
}