Running one-time jobs with Quartz and Spring Boot

Scheduling jobs with Quartz has been discussed numerous times. However, it is worth to know that Quartz can be used not just to run jobs every X hours or based on a CRON expression, but also to execute specific code once at a specified time in the future.

I believe that in some specific use cases, following this approach can dramatically simplify your architecture and implementation. Let's see step by step how to do it.

Setup Quartz ​

Spring Boot comes with first-class support for Quartz: a starter and auto-configuration, so most of the things work out of the box.

First lets add the dependency to spring-boot-starter-quartz:

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-quartz</artifactId>
</dependency>

Define a Job ​

Let's say you want to send a follow-up email to a user 24 hours after they register, asking about their experience so far. To make it happen, you'll need to implement a class that implements org.quartz.Job and turn it into a Spring bean:

import org.quartz.Job;
import org.quartz.JobExecutionContext;
import org.quartz.JobExecutionException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import org.springframework.stereotype.Component;

@Component
public class EmailJob implements Job {
    private static final Logger LOGGER = LoggerFactory.getLogger(EmailJob.class);

    @Override
    public void execute(JobExecutionContext jobExecutionContext) throws JobExecutionException {
        String userId = jobExecutionContext.getJobDetail().getJobDataMap().getString("userId");
        // ...
    }
}

To schedule the job, you'll need to create an instance of org.quartz.JobDetail, which points to the Job that needs to run and can have an execution-specific bag of data called job data. Then create a trigger that defines when the Job with a context defined in JobDetail should run. Finally, call org.quartz.Scheduler#scheduleJob with the JobDetail and Trigger.

import java.util.UUID;

import org.quartz.DateBuilder;
import org.quartz.JobDetail;
import org.quartz.Scheduler;
import org.quartz.SchedulerException;
import org.quartz.Trigger;

import org.springframework.stereotype.Service;

import static org.quartz.DateBuilder.futureDate;
import static org.quartz.JobBuilder.newJob;
import static org.quartz.TriggerBuilder.newTrigger;

@Service
public class RegistrationService {
    private final Scheduler scheduler;

    public RegistrationService(Scheduler scheduler) {
        this.scheduler = scheduler;
    }

    void registerUser(User user) throws SchedulerException {
        // save user
        // ...
        // schedule email
        JobDetail job = newJob(EmailJob.class)
                .withIdentity("email-job-" + user.id())
                .usingJobData("userId", user.id())
                .build();
        Trigger trigger = newTrigger()
                .withIdentity("trigger-email-job-" + user.id())
                .startAt(futureDate(24, DateBuilder.IntervalUnit.HOUR))
                .build();

        scheduler.scheduleJob(job, trigger);
    }
}

To quickly summarize above code: when registerUser method is called, Quartz schedules to run an EmailJob with a userId in the job data, exactly in 24 hours from now.

JobDetails#identity and Trigger#identiy must be unique. You can't schedule two jobs with the same identity.

Persisting Jobs in a database ​

Thankfully, Quartz supports JDBC store, which stores jobs in a relational database. To activate it, you need to configure Quartz in Spring Boot's application.properties.

spring.quartz.job-store-type=jdbc
spring.quartz.jdbc.initialize-schema=always

On application startup, Quartz creates all the tables it needs, but when you try to schedule a job, you might get an exception:

org.quartz.JobPersistenceException: Couldn't acquire next trigger: Couldn't retrieve trigger: Bad value for type long : \x
       at org.quartz.impl.jdbcjobstore.JobStoreSupport.acquireNextTrigger(JobStoreSupport.java:2923) ~[quartz-2.3.2.jar:na]
       at org.quartz.impl.jdbcjobstore.JobStoreSupport$41.execute(JobStoreSupport.java:2805) ~[quartz-2.3.2.jar:na]
       at org.quartz.impl.jdbcjobstore.JobStoreSupport$41.execute(JobStoreSupport.java:2803) ~[quartz-2.3.2.jar:na]
       at org.quartz.impl.jdbcjobstore.JobStoreSupport.executeInNonManagedTXLock(JobStoreSupport.java:3864) ~[quartz-2.3.2.jar:na]
       at org.quartz.impl.jdbcjobstore.JobStoreSupport.acquireNextTriggers(JobStoreSupport.java:2802) ~[quartz-2.3.2.jar:na]
       at org.quartz.core.QuartzSchedulerThread.run(QuartzSchedulerThread.java:287) ~[quartz-2.3.2.jar:na]
Caused by: org.quartz.JobPersistenceException: Couldn't retrieve trigger: Bad value for type long : \x
       at org.quartz.impl.jdbcjobstore.JobStoreSupport.retrieveTrigger(JobStoreSupport.java:1538) ~[quartz-2.3.2.jar:na]
       at org.quartz.impl.jdbcjobstore.JobStoreSupport.acquireNextTrigger(JobStoreSupport.java:2854) ~[quartz-2.3.2.jar:na]
       ... 5 common frames omitted
Caused by: org.postgresql.util.PSQLException: Bad value for type long : \x
       at org.postgresql.jdbc.PgResultSet.toLong(PgResultSet.java:3233) ~[postgresql-42.5.4.jar:42.5.4]
       at org.postgresql.jdbc.PgResultSet.getLong(PgResultSet.java:2449) ~[postgresql-42.5.4.jar:42.5.4]
       at org.postgresql.jdbc.PgResultSet.getBlob(PgResultSet.java:455) ~[postgresql-42.5.4.jar:42.5.4]
       at org.postgresql.jdbc.PgResultSet.getBlob(PgResultSet.java:441) ~[postgresql-42.5.4.jar:42.5.4]
       at com.zaxxer.hikari.pool.HikariProxyResultSet.getBlob(HikariProxyResultSet.java) ~[HikariCP-5.0.1.jar:na]
       at org.quartz.impl.jdbcjobstore.StdJDBCDelegate.getObjectFromBlob(StdJDBCDelegate.java:3190) ~[quartz-2.3.2.jar:na]
       at org.quartz.impl.jdbcjobstore.StdJDBCDelegate.selectTrigger(StdJDBCDelegate.java:1780) ~[quartz-2.3.2.jar:na]
       at org.quartz.impl.jdbcjobstore.JobStoreSupport.retrieveTrigger(JobStoreSupport.java:1536) ~[quartz-2.3.2.jar:na]
       ... 6 common frames omitted

To fix it, you must set a Quartz property org.quartz.jobStore.driverDelegateClass with the value specific to the database type you use. For PostgreSQL it is org.quartz.impl.jdbcjobstore.PostgreSQLDelegate.

spring.quartz.properties.org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate

Quartz creates following database tables:

• qrtz_blob_triggers
• qrtz_calendars
• qrtz_cron_triggers
• qrtz_fired_triggers
• qrtz_job_details
• qrtz_locks
• qrtz_paused_trigger_grps
• qrtz_scheduler_state
• qrtz_simple_triggers
• qrtz_simprop_triggers
• qrtz_triggers

Once the job is scheduled, a row is added to qrtz_simple_triggers and qrtz_job_details. When the job execution is over, entries get deleted. But, that means we lose track of jobs that have already run. To avoid this, make JobDetails durable with storeDurably():

JobDetail job = newJob(EmailJob.class)
    .withIdentity("email-job-" + user.id())
    .usingJobData("userId", UUID.randomUUID().toString())
    .storeDurably()
    .build();

One last thing: by default, Job data set on JobDetails is serialized to bytes using Java serialization. Sure, you can pass any serializable object, but you'll have to deal with potential issues with Java serialization. So, instead, configure Quartz to save job data as a simple properties map and only pass strings, numbers, or booleans:

spring.quartz.properties.org.quartz.jobStore.useProperties=true

Quartz tables database schema ​

As previously discussed, Quartz offers a convenient feature that automates the creation of database tables through the adjustment of the spring.quartz.jdbc.initialize-schema setting to always. However, this approach can result in a lack of control over the database schema implemented by the application, potentially leading to hard to predict behavior when upgrading to a new Quartz version that changes the schema.

To mitigate this issue, a superior approach involves modifying the setting to never and creating a Flyway/Liquibase migration file by copying the database-specific SQL file from Quartz's sources: https://github.com/quartz-scheduler/quartz/tree/main/quartz/src/main/resources/org/quartz/impl/jdbcjobstore

Conclusion ​

Hope this was clear and you find it useful. Feel free to drop a comment if you found any mistake or have a question. Also, feel free to reach out to me on twitter.com/maciejwalkowiak.