Recurring jobs
A recurring job is a job name with a Recurrence. Every node registers it on startup; bikesched
keeps exactly one run pending at a time. It is scheduled like a one-off job, with a Recurrence
instead of a time:
bikesched.newJob("cleanup")
.handler(job -> cleanup())
.schedule(Recurrence.daily(LocalTime.of(3, 0), ZoneId.of("Europe/Berlin")));| Call | First occurrence |
|---|---|
schedule(recurrence) |
the recurrence’s next run from now |
schedule(recurrence, Instant firstRun) |
at firstRun |
schedule(recurrence, Duration delay) |
once delay has passed |
schedule(String recurrence) |
like schedule(recurrence), parsed from an expression, see Recurrence expressions |
schedule(String recurrence, Duration delay) |
once delay has passed, the recurrence parsed from an expression |
Unlike the one-off schedule calls, registering a recurring job is idempotent: it only creates
the first occurrence if none is pending, so every node can run the same code on every start. It
returns the id of the pending occurrence.
Recurrences
Recurrence.every(Duration)(a fixed rate),Recurrence.everyAfterEnd(Duration)(a fixed delay),Recurrence.daily(LocalTime, ZoneId),Recurrence.weekly(DayOfWeek, LocalTime, ZoneId), or your own viaRecurrence.of(description, previous -> next).- Each occurrence stores the time it was planned for (
planned_run_at), and the next run is computed from it, so retries, sleeps and event waits that move an occurrence don’t shift the ones after it. Runs whose time has passed when an occurrence ends are skipped:every(PT15M)started at 12:00 and running for 20 minutes is followed by the run at 12:30. - Recurrences that snap to the wall clock (
daily,weekly, cron) returntruefromisWallClock(): after missed runs, the next run is computed from the current time in one step. A custom recurrence that returns the first match after any instant can do the same. - Each occurrence stores the recurrence’s description. Registering a recurrence with a different description (e.g. after a deploy) moves the pending occurrence to the new recurrence.
Fixed delay
Recurrence.everyAfterEnd(Duration) computes the next run from the time the previous occurrence
ended instead of its planned run, like Spring’s fixedDelay. Every run is followed by the same
gap, however long it took:
bikesched.newJob("sync-crm")
.handler(job -> crm.sync())
.schedule(Recurrence.everyAfterEnd(Duration.ofMinutes(15)));- A run ending at 12:10 is followed by the next one at 12:25, whether it started at 12:00 or at 12:09. No run is skipped.
- The end is whatever ends the occurrence: it succeeded, failed permanently (after its failure handler) or was cancelled, after its compensations if it has any. Retries, sleeps, event waits and postponements belong to the run.
- Cancelling the pending occurrence before its planned run skips one run: the next one is computed from the cancelled occurrence’s planned run, as with a fixed rate.
- The description is
every PT15M after end. The first occurrence runs one interval after registration, or at thefirstRunor after thedelaygiven toschedule. - With annotations, declare it with
@JobHandler(fixedDelay = "PT15M"), see Annotations.
Recurrence expressions
schedule(String) and @JobHandler(schedule = …) take a recurrence as a string, parsed by the
node’s RecurrenceParsers:
bikesched.newJob("cleanup").handler(job -> cleanup()).schedule("PT1H");- By default a node has one parser,
RecurrenceParser.isoDuration(): ISO-8601 durations (PT1H), run likeRecurrence.every(Duration)at a fixed rate. BikeschedBuilder.recurrenceParsers(…)replaces the set; listisoDuration()as well to keep durations. A parser is asupports(expression)check plusparse(expression); an expression must be supported by exactly one parser, otherwiseschedule(String)throws anIllegalArgumentException, as it does for an invalid expression.- Expressions suit schedules from configuration; in code, a
Recurrenceis checked by the compiler.
Cron expressions
The module bikesched-cron adds CronRecurrence, parsed with
cron-utils and evaluated in a time zone:
bikesched.newJob("report")
.handler(job -> sendReport())
.schedule(CronRecurrence.of("0 3 * * MON-FRI", ZoneId.of("Europe/Berlin")));-
CronRecurrence.of(expression, zone)takes a Unix expression (five fields, minute precision);CronRecurrence.of(expression, CronType, zone)another cron-utils dialect, e.g.CronType.QUARTZorCronType.SPRING53with a seconds field. -
Invalid expressions and expressions without a future execution (
0 0 30 2 *) are rejected with anIllegalArgumentExceptionwhen the recurrence is created. -
The description is the dialect, the normalized expression and the zone (
cron unix 0 3 * * 1-5 Europe/Berlin), so changing any of them moves the pending occurrence. Cron snaps to the wall clock. -
Daylight saving time: a local time that doesn’t exist on a day (clocks moving forward) is skipped that day — unlike
Recurrence.daily, which shifts it. A local time that occurs twice (clocks moving back) runs once if the expression names the hour (30 2 * * *) and in both passes if the hour is a wildcard (*/30 * * * *). -
CronRecurrenceParserparses cron expressions given as strings, in its dialect (Unix by default) and zone (UTC by default):Bikesched.builder(dataSource) .recurrenceParsers(RecurrenceParser.isoDuration(), new CronRecurrenceParser(CronType.UNIX, ZoneId.of("Europe/Berlin"))) … bikesched.newJob("report").handler(job -> sendReport()).schedule("0 3 * * MON-FRI");
Occurrences
- The job name identifies the recurring job. Each run is an occurrence, a regular job of type
RECURRINGwith its own retries, timeout, steps and events. At most one occurrence is pending at a time, enforced by a partial unique index. - When an occurrence ends (succeeded, permanently failed, or cancelled, which cancels only that occurrence), the next one is inserted in the same transaction. Runs missed while no node was up are skipped.
- Registering a recurring job recreates a missing occurrence; a node also checks all its recurring
jobs once when it starts polling, retried every
nodeCleanUpIntervalif that fails. bikesched.removeRecurringJob(name)stops a recurring job that is no longer registered anywhere.connection(...)leads to a builder withoutschedule(Recurrence), so a recurring job can’t be scheduled in the caller’s transaction.