Comandi iniziali degli eventi pianificati ricorrenti

Tre diversi comandi iniziali ti consentono di pianificare un'automazione in anticipo:

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

Il primo, Time.ScheduledTimeEvent, ti consente di pianificare l'avvio di un'automazione in un singolo istante preciso nel futuro o su base ricorrente, in base all'ora o a un evento solare (ovvero alba o tramonto).

Ad esempio, questo comando iniziale avvia l'automazione alle 22:00 ogni giorno:

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

In alternativa, puoi specificare l'evento di ora solare anziché l'ora. Il parametro per questo tipo di comando iniziale è una SolarTimeStruct composta da:

1. type, che è SolarTimeType.Sunrise o SolarTimeType.Sunset.
2. offset, che ti consente di spostare l'ora di inizio rispetto all'evento solare di un qualsiasi periodo di tempo. I valori positivi introducono un ritardo dopo l'evento solare, mentre i valori negativi fanno sì che il comando iniziale venga attivato prima dell'evento solare.

L'esempio seguente è un comando iniziale che avvia l'automazione 15 minuti prima dell'alba ogni giorno:

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

Gli altri due comandi iniziali sono comandi iniziali di eventi pianificati ricorrenti, che ti consentono di creare automazioni che vengono eseguite periodicamente in base a criteri più specifici che possono includere condizioni basate su ora e calendario.

Time.RecurringClockTimeScheduledEvent ti consente di pianificare un'automazione in base a una o più condizioni di ora o data. Questo comando iniziale utilizza una sintassi simile a quella utilizzata dall'utilità cron di Unix per specificare la pianificazione di un'automazione ricorrente.

Time.RecurringSolarTimeScheduledEvent ti consente di pianificare un'automazione in base all'ora di alba o tramonto, facoltativamente in combinazione con una condizione basata sul calendario.

Espressioni cron

Potresti già conoscere cron, un comando utilizzato sui sistemi Unix e Linux per pianificare job ricorrenti.

I comandi iniziali di eventi pianificati ricorrenti utilizzano una sintassi di espressione di pianificazione simile a quella utilizzata da cron e, per questo motivo, le espressioni di pianificazione utilizzate con questi comandi iniziali sono denominate espressioni cron.

Esistono diverse "varianti" di cron e diverse varianti di sintassi in queste implementazioni. Le espressioni cron dei comandi iniziali di eventi pianificati ricorrenti utilizzano la stessa sintassi dello scheduler Quartz. La sintassi delle espressioni cron di Quartz è spiegata in the documentation for Quartz's CronExpression.

Esempi

Ecco alcuni esempi per illustrare.

RecurringClockTimeScheduledEvent

In un comando iniziale RecurringClockTimeScheduledEvent, la stringa dell'espressione cron viene assegnata al Time.RecurringClockTimeScheduledEvent.cronExpression campo.

Di seguito è riportato un esempio di comando iniziale RecurringClockTimeScheduledEvent che avvia l'automazione alle 20:00, ogni mercoledì di aprile:

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

RecurringSolarTimeScheduleEvent

Il comando iniziale RecurringSolarTimeScheduleEvent accetta due parametri:

1. Una SolarTimeStruct.
2. cronExpression: un sottoinsieme di un'espressione cron composta solo dai campi Giorno del mese, Mese, Giorno della settimana e Anno. L'ora solare determina l'ora esatta in cui verrà avviata l'automazione, pertanto i campi Secondo, Minuto e Ora vengono omessi.

L'esempio seguente è un comando iniziale che avvia un'automazione un'ora dopo l'alba, ogni mercoledì di aprile:

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