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 na hora do relógio ou em um evento solar (ou seja, nascer ou pôr do sol).

Por exemplo, este ponto de partida 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, você pode especificar um evento de horário solar em vez de horário de relógio. O parâmetro para esse tipo de acionador é 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 ponto de partida que inicia a automação 15 minutos antes do amanhecer 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 agenda.

Com o Time.RecurringClockTimeScheduledEvent, você pode programar uma automação com base em uma ou mais condições de data ou hora. Esse iniciador 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.

cron expressões

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

Os iniciadores de eventos recorrentes programados 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. Os iniciadores de eventos recorrentes programados 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 RecurringClockTimeScheduledEvent, a string de expressão cron é atribuída ao campo Time.RecurringClockTimeScheduledEvent.cronExpression.

Confira um exemplo de um iniciador do RecurringClockTimeScheduledEvent que começa 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 iniciador 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 momento 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 iniciador 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 *"))
}