Spring Boot
The module bikesched-spring-boot-starter (package org.bikesched.spring, Spring Boot 4.1) wires a
Bikesched node from the application context: with a DataSource bean present, the context gets a
node, the @JobHandler methods of its beans are registered and polling starts with the application.
No @EnableBikesched, no builder code. Scheduling stays the application’s job: inject Bikesched
and call newJob(…) from anywhere. Core stays free of Spring; only this module depends on it.
Quick start
dependencies {
implementation("org.bikesched:bikesched-spring-boot-starter:0.2.0-SNAPSHOT")
implementation("org.springframework.boot:spring-boot-starter-jdbc") // a pooled DataSource
}spring.datasource.url=jdbc:postgresql://localhost:5432/bikesched
spring.datasource.username=bikesched
spring.datasource.password=bikesched@SpringBootApplication
public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }
@Component
class InvoiceJobs {
@JobHandler(name = "send-invoice")
public void sendInvoice(Job job, Invoice invoice) { mailer.send(invoice); }
}Anywhere else: @Autowired Bikesched bikesched; bikesched.newJob("send-invoice").payload(…).schedule();.
The Spring example, a regular Spring Boot
application in bikesched-examples/spring, runs this against the compose database
(./gradlew :bikesched-examples:spring:bootRun) and shows transactional scheduling and event
publishing with two services that share no data.
Handlers
Discovery finds every bean with @JobHandler or @JobFailureHandler methods — including
AOP-proxied ones (@Transactional, @Cacheable, …) — and invokes them through the proxy, so
the advice applies. Beans implementing StandaloneJobHandler or StandaloneJobFailureHandler are
registered the same way (plain JobHandler and JobFailureHandler beans carry no job name and are
ignored). Registration happens before polling starts, so a node never claims a job it cannot run; a
bean created later (@Lazy, prototype) registers when it is created. Duplicates fail startup with a
message naming the bean and the method — there is no way to downgrade this to a warning, and none
intended. See Annotations for the method signature rules.
Recurring handlers: the starter configures the node’s
recurrence parsers with ISO-8601 durations and
Spring’s six-field CronExpression syntax, so a handler can declare its schedule next to its name:
@JobHandler(name = "purge-expired-sessions", schedule = "0 0 */6 * * *")
public void purgeExpiredSessions() { … }The schedule is evaluated in UTC and uses the expression itself as its stable recurrence
description. ISO-8601 durations, e.g. @JobHandler(name = "refresh-cache", schedule = "PT15M"),
run at a fixed rate. The same expressions work in newJob(name).schedule("PT15M").
Spring’s @Scheduled attributes map to @JobHandler like this: fixedRate to schedule with an
ISO-8601 duration, cron to schedule with a cron expression, fixedDelay to fixedDelay (a
fixed delay) and initialDelay to initialDelay. Without
initialDelay, the first run is one interval after registration, not right away as with Spring’s
default of 0. Unlike Spring’s, the initial delay only applies to a new first occurrence:
restarting the application keeps the pending one.
Every RecurrenceParser bean is added to these two, so an application can add its own formats. For
other cron dialects or a time zone other than UTC, add bikesched-cron and declare its parser as a
bean; the starter doesn’t configure it. Its syntax must not overlap with the built-in parsers’,
because each expression must be supported by exactly one parser. Unix expressions have five fields,
so they never match the six-field Spring syntax:
@Bean
RecurrenceParser unixCronParser() {
return new CronRecurrenceParser(CronType.UNIX, ZoneId.of("Europe/Berlin"));
}A BikeschedCustomizer runs after this and can replace the whole set with
builder.recurrenceParsers(…).
See Cron expressions.
Transactional handlers: a handler runs on a bikesched job thread, never inside an ambient
transaction, so @Transactional with the default propagation REQUIRED simply starts a new one —
REQUIRES_NEW written explicitly documents that intent. The starter logs a warning once per handler
method that uses the default propagation; it only sees annotations, so a handler that uses a
TransactionTemplate needs no annotation and gets no warning. Step results and job state are always
written by bikesched outside the handler’s transaction, like anywhere else
(steps.md).
Scheduling and publishing inside your transaction: pass the transaction’s connection to the builder, and the job row (or event) commits and rolls back with it:
@Transactional
public UUID placeOrder(String customer, String item) {
Order order = orders.save(new Order(customer, item));
return bikesched.newJob(FULFILL_ORDER)
.payload(new FulfillOrder(order.getId()))
.connection(BikeschedTransactions.transactionalConnection(dataSource))
.schedule();
}BikeschedTransactions.transactionalConnection(dataSource) returns the connection bound to the
caller’s transaction for that DataSource, or null without one (then the builder schedules
autonomously). Recurring jobs cannot be scheduled this way — their registration lives in the node’s
memory. The same applies to newEvent(name, key).connection(…).publish().
Lifecycle
The node is built with polling disabled, and a SmartLifecycle (last phase) starts it once the rest
of the context is up: it initializes the database (see below) and registers the node,
sends heartbeats and polls. On shutdown, Spring closes the node before destroying the DataSource
it uses: unfinished jobs are released and running handlers awaited (bounded by their timeouts), so
another node takes over. Spring’s own shutdown hook closes the context on JVM shutdown, so the
starter leaves the builder’s closeOnShutdown off: a second hook would close the node in no order
with the DataSource.
bikesched.auto-start.enabled=falsebuilds a node that schedules only: it registers with no database, executes nothing and sends no heartbeats. Callstart()yourself later if such an instance should also work.- Node names need not be unique: a second context with the same name starts as a node of its own.
Distinct
bikesched.node-names keep several nodes in one JVM apart in logs and the admin UI.
Schema migration
bikesched.migrate-schema maps directly to the core migrateSchema flag and defaults to true.
The starter does not call Bikesched.migrate() explicitly. Initialization happens on first database
use: starting polling triggers it during startup, while a scheduling-only instance defers it.
migrate-schema |
auto-start.enabled |
Behavior |
|---|---|---|
true (default) |
true (default) |
Migrate at startup, then register the node and poll. |
true |
false |
No startup database access; migrate on first database use. |
false |
true |
Validate migration history at startup, then register the node and poll. |
false |
false |
No startup database access; validate history on first database use. |
To run without DDL privileges, migrate separately with a migration-capable data source, then set:
bikesched:
migrate-schema: falseValidation reads migration history without DDL or history writes. Missing history/versions or a
checksum mismatch fails startup when polling is enabled, otherwise the first database operation.
It is not physical schema drift detection; see database
migrations for permissions and deployment ordering.
auto-start.enabled only controls polling, not DDL permission. An application calling
Bikesched.migrate() explicitly still requests migration regardless of the flag; that call requires
migration privileges and does not start polling.
Properties
Every builder option (configuration.md) has a bikesched.*
property; unset ones keep the builder default. Relaxed binding applies (poll-interval: 1500ms and
friends).
| Property | Default | Note |
|---|---|---|
bikesched.node-name |
<spring.application.name>-<host name> |
node name in logs and the admin UI; the host name keeps replicas apart |
bikesched.data-source |
the single / @Primary DataSource |
the bean name of the one to use, never a JDBC URL; with several candidates and neither the property nor a @Primary, the context fails listing them |
bikesched.poll-interval |
10 seconds | safety net while listening, see Due jobs |
bikesched.listen-for-due-jobs |
true |
holds one pool connection; false behind PgBouncer in transaction mode |
bikesched.notify-interval |
100 ms | |
bikesched.heartbeat-interval |
5 seconds | |
bikesched.node-timeout |
30 seconds | must be longer than the heartbeat interval (validated) |
bikesched.max-concurrent-jobs |
10 | |
bikesched.auto-start.enabled |
true |
see Lifecycle |
bikesched.default-job-timeout |
none | |
bikesched.default-event-timeout |
none | |
bikesched.retry-backoff.fixed or bikesched.retry-backoff.exponential.{initial,max} |
none | mutually exclusive; other combinations fail the context |
bikesched.failure-handler-attempts |
3 | |
bikesched.event-retention |
7 days | |
bikesched.event-clean-up-interval |
1 hour | |
bikesched.node-clean-up-interval |
15 seconds | |
bikesched.history-retention |
off | enables the history |
bikesched.history-clean-up-interval |
1 hour | |
bikesched.job-retention |
7 days | |
bikesched.job-clean-up-interval |
1 hour | |
bikesched.statement-timeout |
data source | |
bikesched.hard-timeout-grace |
off | |
bikesched.migrate-schema |
true |
migrate on first database use; false validates history only, see Schema migration |
bikesched.metrics.enabled |
true |
only relevant with Micrometer (below) |
A BikeschedCustomizer bean (a void customize(BikeschedBuilder) functional interface, applied in
@Order after the properties) covers everything else — another JsonMapper, a listener, a
computed timeout — and a user-defined Bikesched bean makes the auto-configuration back off
entirely (define one in tests if you want to set builder options directly).
JSON and metrics
With bikesched-jackson on the classpath, the starter registers a JsonMapper built from the
context’s Jackson 3 ObjectMapper (Boot’s JacksonAutoConfiguration, or yours) — so job payloads
are ordinary records, mapped exactly like the rest of the application serializes JSON. Without the
module, payloads stay JSON strings
(configuration.md). A user JsonMapper bean
wins.
With bikesched-micrometer and a MeterRegistry bean (Boot’s Actuator/micrometer registry), an
automatic MicrometerJobListener and MicrometerEventListener record the meters of
metrics.md, tagged node with the resolved node name — so nodes sharing
a registry do not overwrite each other’s gauges. Turn both off with
bikesched.metrics.enabled=false, or replace either with your own MicrometerJobListener or
MicrometerEventListener bean.
All JobListener beans in the context are composed and passed to the node; each gets the same
events. The same goes for org.bikesched.event.listener.EventListener beans (not to be confused
with Spring’s @EventListener annotation).
Out of scope (v1)
Actuator health indicators and any interop with @Scheduled or Spring Batch.