24. Cron expressions via cron-utils in their own module
Date: 2026-10-07
Status
Accepted
Context
Recurring jobs run on a Recurrence; core offers every, daily, weekly and custom
recurrences, and recurrence expressions given as strings are parsed by the node’s
RecurrenceParsers (ADR 0025). Users expect cron expressions. The Spring Boot starter parses
Spring’s six-field CronExpression, evaluated in UTC; plain Java applications have no cron support,
and Spring applications can’t choose another dialect or zone.
Alternatives considered:
- Spring’s
CronExpression: one dialect, pulls inspring-contextfor non-Spring users. - A cron parser of our own in core: a dialect to maintain, against the “minimal core” rule.
- cron-utils 9.2.1: Apache 2.0, Unix, Quartz, Spring and
cron4j dialects,
ExecutionTime.nextExecution, onlyslf4j-apias a dependency, anAutomatic-Module-Name(com.cronutils). Its last release is from March 2023, though the repository is still maintained.
Decision
A module bikesched-cron (package org.bikesched.cron) depends on core and cron-utils only (both
api; cron-utils’ CronType is part of the API) and provides:
CronRecurrence, a publicRecurrence:of(expression, zone)for Unix expressions,of(expression, CronType, zone)for other dialects. Invalid expressions and expressions without a future execution are rejected on creation. The description iscron <dialect> <normalized expression> <zone>, so a changed expression, dialect or zone moves the pending occurrence. Not fixed rate.CronRecurrenceParser, aRecurrenceParserfor one dialect and zone (Unix and UTC by default), forschedule(String)and@JobHandler(schedule = …).
The Spring Boot starter keeps its Spring CronExpression parser and does not configure the
bikesched-cron one; applications that want it declare it as a RecurrenceParser bean with their
dialect and zone, which is added to the built-in parsers.
Consequences
- Plain Java, annotation and Spring users share one cron implementation, with the dialect and zone chosen explicitly.
- Daylight saving time follows cron-utils: a non-existent local time is skipped that day, a repeated one runs once for a fixed hour and twice for a wildcard hour; tests pin this down.
- In Spring, a bikesched-cron parser whose dialect overlaps with the built-in six-field syntax
(
SPRING,SPRING53,QUARTZwithout a year) makes such expressions ambiguous: registering fails with “Multiple RecurrenceParsers support recurrence”. Unix (five fields) doesn’t overlap. - The normalized expression comes from cron-utils (
asString()); if an upgrade changes it, pending occurrences are moved once to the same schedule.