Ativações de eventos programados recorrentes

Três inicializadores diferentes permitem programar uma automação com antecedência:

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

O primeiro, Time.ScheduledTimeEvent, permite programar uma automação para iniciar 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, esse inicializador 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 o evento de horário solar em vez do horário do 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 por qualquer período. Valores positivos introduzem um atraso após o evento solar, e valores negativos fazem com que o inicializador seja acionado antes do evento solar.

O exemplo a seguir é um inicializador 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 outros dois inicializadores são inicializadores de eventos programados recorrentes, 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 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 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 inicializadores de eventos programados recorrentes usam uma sintaxe de expressão de programação semelhante à usada pelo cron. Por esse motivo, as expressões de programação usadas com esses inicializadores 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 cron do inicializador de eventos programados recorrentes usam a mesma sintaxe do agendador Quartz. A sintaxe da expressão cron do Quartz é explicada em a documentação do Quartz's CronExpression.

Exemplos

Confira alguns exemplos para ilustrar.

RecurringClockTimeScheduledEvent

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

Confira um exemplo de um inicializador RecurringClockTimeScheduledEvent que inicia a automação às 20h de cada quarta-feira 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. Um 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 "Segundo", "Minuto" e "Hora" são omitidos.

O exemplo a seguir é um inicializador que faz com que uma automação seja iniciada 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 *"))
}