Ativações de eventos programados recorrentes

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 10h todos os dias:

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

Como alternativa, você pode 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 composto por:

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 ativador seja acionado antes do evento solar.

O exemplo a seguir é um iniciador 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))
    )
  )
}

As duas segundas ativações são ativações 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 data ou hora. Esse modelo 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 no calendário.

Expressões cron

Você já deve conhecer 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 por cron. Por esse motivo, 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 cron de início de evento programado recorrentes usam a mesma sintaxe do programador Quartz. A sintaxe da expressão cron do Quartz é explicada na documentação do CronExpression do Quartz.

Exemplos

Confira alguns exemplos para ilustrar.

RecurringClockTimeScheduledEvent

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

Confira a seguir um exemplo de ativação RecurringClockTimeScheduledEvent que inicia a automação às 20h, todas as quartas-feiras em 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. Portanto, os campos "Segundo", "Minuto" e "Hora" são omitidos.

O exemplo a seguir é um ativador que faz com que uma automação seja iniciada uma hora após o nascer do sol, todas as quartas-feiras em abril:

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