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 chiamate 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 dell'espressione 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 fa sì che un'automazione venga avviata 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 *"))
}