Dynamic Scheduling & Management

The convention used here and on the other pages: the reminder of loan 1001 has job key and trigger key loan-1001 in the group reminders, the job class is MemberReminderJob, and the job data holds memberId and loanId. Using the loan identifier in the key makes every operation idempotent and lets any node, or an operator, find a reminder without a lookup table.

The figure is what the rest of the page implements: the first half in the services, the transaction boundary in Transactional consistency, and the alt branch is why the job must re-check the loan (a reminder can fire for a loan that was returned a moment earlier).

Spring Boot’s spring-boot-starter-quartz registers one Scheduler bean (bean name quartzScheduler, scheduler name from spring.quartz.scheduler-name, here BookshelfScheduler). With the JDBC store its job store is LocalDataSourceJobStore and getMetaData().isJobStoreSupportsPersistence() is true, which the first line of the run confirmed. Inject it like any bean; every method below throws SchedulerException (a checked exception) unless the table says otherwise, and every call goes through the store, so on a clustered JDBC store a change made on one node is seen by all of them, see Clustering.

The examples on this page ran with this configuration: the JDBC store on PostgreSQL, the schema created beforehand by a migration (the tests let Boot create it), and the credentials from the environment.

Source: Spring Boot: Quartz Scheduler. Used by every test of this page on Boot 4.1.1; the tests override the three datasource properties with the Testcontainers values and set initialize-schema=always (which drops and recreates the tables, test use only, see Job Stores & Persistence).

The Quartz cookbook has a small set of "how-to" pages for exactly the operations of this page: listing (ListJobs, ListTriggers, JobTriggers), changing (UpdateJob, UpdateTrigger), removing (UnscheduleJob) and storing for later (StoreJob, ScheduleStoredJob). Each one was run against the JDBC store, and two of them do not work exactly as printed.

Source: StoreJob, ScheduleStoredJob, ListJobs, ListTriggers, JobTriggers, UpdateJob, UpdateTrigger and UnscheduleJob (all Quartz Cookbook). Run in a test project on Quartz 2.5.2 and PostgreSQL 17.11.

The corrected UpdateJob and the portable UpdateTrigger are worth keeping as snippets:

Source: Quartz Cookbook — Update an existing job and Quartz Cookbook — Updating a trigger. The same calls ran in a test project (the reschedule form is the one the REST API below uses, run through PUT /api/reminders/1001 returning 204). Note that storeDurably() here also makes a replaced reminder job survive the deletion of its last trigger.

The service layer is a thin wrapper that owns the key convention. It uses the create-or-replace form, so posting the same loan twice is harmless, and deleteJob for cancellation, so cancelling twice is a 404 the second time rather than an error.

Source: Scheduler Javadoc and Quartz Cookbook — Listing Jobs in the Scheduler. Compiled and run on Spring Boot 4.1.1 with the JDBC store; the two continue lines exist because a one-shot reminder can fire and disappear between getJobKeys and the lookups, so getJobDetail returns null and a finished trigger has no next fire time.

The job class is the QuartzJobBean of the triggers page, with the mail gateway injected through the constructor (Spring creates jobs, so constructor injection works) and memberId and loanId set from the job data:

Source: Spring Framework: Task Execution and Scheduling. Run on Spring Boot 4.1.1: the job received its ReminderSender and the values 42 and 1001.

The controller is ordinary Spring MVC. It maps the four operations to HTTP verbs and the "nothing there" results of the Scheduler API to 404:

Source: Spring Framework: Task Execution and Scheduling and Spring Security: Method Security. Compiled against Boot 4.1.1 (spring-boot-starter-webmvc) and exercised with MockMvc, results in the next table. The SchedulerException is declared rather than caught: it is a failure of the store (database down), which should surface as a 500, see REST APIs for a global @ExceptionHandler.

The requests were sent with MockMvc against the real Spring Security filter chain and the PostgreSQL job store (the next section shows the security setup):

Source: Spring Boot: Testing Spring Boot Applications. Run on Boot 4.1.1 in a test project (@SpringBootTest with @AutoConfigureMockMvc, imported from org.springframework.boot.webmvc.test.autoconfigure, and @WithMockUser); the timestamps are from the run.

An endpoint that can create and delete schedules is an administrative interface: anyone who can post to it decides what runs and when, and a job class name must never come from the request (the controller above fixes MemberReminderJob and takes only identifiers and an instant, so nothing the client sends is turned into a class name or a cron expression). The security model, filters and method security are explained on Spring Security; the part that matters here is small.

Source: Spring Security: Authorize HttpServletRequests and Spring Security: Method Security. Compiled and run on Spring Security 7.1.1 (Boot 4.1.1); withDefaults is the static import of org.springframework.security.config.Customizer.withDefaults. HTTP Basic stands in for your real authentication (JWT, OAuth 2.0, see Spring Security); users come from a UserDetailsService, no password appears in the code.

Two rules are worth stating. Put the coarse rule in the filter chain (/api/** needs authentication, everything else is denied) and the fine rule next to the method (hasRole('LIBRARIAN'), or the own-reminders expression for members), so that a new endpoint added to the controller without an annotation is still at least authenticated. And switch method security on: the same controller was run with @EnableMethodSecurity commented out, and the @PreAuthorize annotations were silently ignored, so the MEMBER user got 201 on POST, 204 on DELETE, and could read member 7’s reminders with 200. CSRF protection is disabled here only because the API is stateless and authenticated by a header on every request; a browser session needs it. Do not expose the Actuator quartz endpoint without the same care, see Observability.

The loan row and its reminder are two writes, and they should succeed or fail together: a reminder for a loan that was rolled back mails a member about a loan that does not exist, and a loan whose reminder was lost never reminds anyone. With the JDBC store they can share one transaction, because of how Spring Boot wires Quartz: LocalDataSourceJobStore asks DataSourceUtils for its connection, and DataSourceUtils returns the connection that the current Spring transaction has bound to that DataSource. If the DataSource Quartz uses is the same one the business code uses, every QRTZ_* insert made by scheduleJob happens on the same connection as the INSERT INTO loan, and commits or rolls back with it. (The JobStoreCMT that LocalDataSourceJobStore extends is Quartz’s "container managed" store: it never commits itself.)

Source: Spring Framework: Transaction Management and SchedulerFactoryBean Javadoc; behaviour read from LocalDataSourceJobStore in Spring Framework 7.0.9. rollbackFor = Exception.class matters because SchedulerException is checked and a Spring transaction does not roll back on checked exceptions by default. The test version of lend had an extra flag that throws IllegalStateException after scheduling, to force a rollback.

The measurements, with the business tables and the Quartz tables in one PostgreSQL database (@Primary data source, nothing else) and then in two:

Source: Spring Boot: Quartz Scheduler. Measured in a test run on two PostgreSQL 17.11 containers; the SchedulerFactoryBean receives the Quartz data source, and with a @QuartzDataSource its connections are not the ones bound to the business transaction, so Quartz commits on its own.

Sharing the transaction has a price that the first measurement hides, which is the locking in the store. Scheduling takes the TRIGGER_ACCESS row lock of QRTZ_LOCKS (lockOnInsert is true by default), and a lock taken inside a transaction is held until that transaction ends. Two threads were run: the first scheduled a reminder and then held its transaction open for 2000 ms; a second thread scheduling another reminder 500 ms later waited 1519 ms, whether it did so inside its own transaction or without any (1513 ms). The rule that follows: keep the transaction around scheduleJob short, never call a slow service (a mail gateway, a remote API) between the scheduleJob and the commit, and expect the scheduler’s firing (triggersFired) to queue behind a long business transaction. The locks and what each call takes are on Job Stores & Persistence and PostgreSQL; the general transaction and locking background is on Transaction Isolation & Locking.

Spring’s own TaskScheduler can also schedule a one-shot task at runtime: taskScheduler.schedule(runnable, instant) returns a ScheduledFuture that you can cancel. For a task that only matters while the application is up that is enough, and the whole mechanism is explained on Scheduling and ShedLock. For the Bookshelf reminders it is not, because the schedule exists only as a ScheduledFuture in the heap of one JVM. The next test scheduled the same reminder both ways for five seconds ahead, stopped the application after one second, waited two seconds, and started it again against the same database.

Source: TaskScheduler Javadoc and Spring Framework: Task Execution and Scheduling. Run on Spring Framework 7.0.9 and Quartz 2.5.2 in a test project.

What the run printed, as a timeline from the start of the test:

Source: Quartz documentation: Best Practices. Output of a test run, quoted as measured.

Source: Spring Framework: The TaskScheduler Interface. The first two rows are measured in the run above; the rest follows from the API.

The practical guidance: use TaskScheduler for in-process, loss-tolerant work (a debounce, a short timeout, a retry in a few seconds), and the Quartz Scheduler when the schedule belongs to the business data and must survive a restart, a deployment and the loss of a node. The side-by-side comparison with @Scheduled and ShedLock for fixed schedules is on the section’s comparison page, linked from Scheduling.

Source: Quartz 2.5.x Javadoc: Scheduler and the measurements of this page.

Source: Quartz releases and Spring Boot: Quartz Scheduler. The cookbook rows were verified by running the recipes (see above); the TaskScheduler row from javap on spring-context 7.0.9.

The full list of version changes and documentation discrepancies of the section is on Migration & What’s Changed.