dropwizard-jobs

This plugin integrates the quartz scheduler with dropwizard and allows you to easily create background jobs, which are not bound to the HTTP request-response cycle. Quartz creates a threadpool on application startup and uses it for background jobs.

There are four different types of jobs:

• Jobs run on application start for initial setup (could also be done via a managed instance in dropwizard)
• Jobs run at application stop before the application is closed (could also be done via managed instance in dropwizard)
• Jobs which are repeated after a certain time interval
• Jobs which need to run at a specific time, via a cron-like expression

Using maven central repository

dropwizard jobs can be used with maven. It is located in Central Repository. https://search.maven.org/

Add to your pom:

<dependency>
  <groupId>io.github.dropwizard-jobs</groupId>
  <artifactId>dropwizard-jobs-core</artifactId>
  <version>7.0.0</version> 
</dependency>

Installing the bundle from source code

git clone https://github.com/dropwizard-jobs/dropwizard-jobs
cd dropwizard-jobs
./mvn install

After installing the plugin locally you can include it in your pom.xml

<dependency>
  <groupId>io.github.dropwizard-jobs</groupId>
  <artifactId>dropwizard-jobs-core</artifactId>
  <version>$VERSION</version>
</dependency>

Activating the bundle: Configuration

Your Dropwizard application configuration class must extend JobConfiguration:

public class ApplicationConfiguration extends JobConfiguration {

...

}

Activating the bundle: Initialization

In your application's initialize method, call bootstrap.addBundle(new JobsBundle(<List of jobs>)):

@Override
public void initialize(Bootstrap<MyConfiguration> bootstrap) {
  SomeDependency dependency = new Dependency();
  Job startJob = new StartupJob();
  Job stopJob = new StopJob();
  Job everyJob = new EveryTestJob(dependency);
  bootstrap.addBundle(new JobsBundle(new ArrayList<>(startJob, stopJob, everyJob)));
}

Using HK2 for Dependency Injection

If your jobs require dependencies that are only available at runtime (e.g., Hibernate DAOs, service classes), you can use the separate dropwizard-jobs-hk2 module which leverages Dropwizard's HK2 dependency injection container. Unlike the plain JobsBundle, Hk2JobsBundle defers job discovery to Jersey container startup, so all registered services are available for injection.

Add the HK2 module dependency to your project:

<dependency>
  <groupId>io.github.dropwizard-jobs</groupId>
  <artifactId>dropwizard-jobs-hk2</artifactId>
  <version>7.0.0</version> 
</dependency>

See the HK2 integration documentation for setup instructions and examples.

For Guice users, see the Guice integration documentation.

Available job types

The @OnApplicationStart annotation triggers a job after the quartz scheduler is started

@OnApplicationStart
public class StartupJob extends Job {
  @Override
  public void doJob(JobExecutionContext context) throws JobExecutionException {
    // logic run once on application start
  }
}

The @OnApplicationStop annotation triggers a job when the application is stopped. Be aware that it is not guaranteed that this job is executed, in case the application is killed.

@OnApplicationStop
public class StopJob extends Job {
  @Override
  public void doJob(JobExecutionContext context) throws JobExecutionException {
    // logic run once on application stop
  }
}

The @Every annotation first triggers a job after the quartz scheduler is started and then every n times, as it is configured. You can use a number and a time unit, which can be one of "s" for seconds, "m" or "mn" or "min" for minutes, "h" for hours, "d" for days and "ms" for milliseconds. Use in conjunction with @DelayStart to delay the first invocation of this job.

@Every("1s")
public class EveryTestJob extends Job {
  @Override
  public void doJob(JobExecutionContext context) throws JobExecutionException {
    // logic run every time and time again
  }
}

The @DelayStart annotation can be used in conjunction with @Every to delay the start of the job. Without this, all the @Every jobs start up at the same time when the scheduler starts.

@DelayStart("5s")
@Every("1s")
public class EveryTestJobWithDelayedStart extends Job {
  @Override
  public void doJob(JobExecutionContext context) throws JobExecutionException {
    // logic run every time and time again
  }
}

The @On annotation allows one to use cron-like expressions for complex time settings. You can read more about possible cron expressions at https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/tutorial-lesson-06.html

This expression would run on Mondays at 1pm, Los Angeles time. If the optional parameter timeZone is not set system default will be used.

@On(value = "0 0 13 ? * MON", timeZone = "America/Los_Angeles")
public class OnTestJob extends Job {
  @Override
  public void doJob(JobExecutionContext context) throws JobExecutionException {
    // logic run via cron expression
  }
}

By default a class can only be scheduled once in the jobs bundle, this can be overridden by setting a unique groupName to the instance.

@Every("15m")
public class GroupNameJob extends Job {
  public GroupNameJob(String groupName) {
      super(groupName);
  }
}

Job Listeners

You can register Quartz JobListener implementations to react to job lifecycle events. Job listeners are notified when a job is about to execute, when execution is vetoed, and after a job has executed. This is useful for:

• Clearing thread-local values after job execution
• Adding reporting or metrics for job failures
• Implementing cross-cutting concerns for job execution

Using the @ListeningFor Annotation

Create a class that implements JobListener and annotate it with @ListeningFor:

@ListeningFor
public class MyJobListener implements JobListener {
    @Override
    public String getName() {
        return "MyJobListener";
    }

    @Override
    public void jobToBeExecuted(JobExecutionContext context) {
        // Called before job executes
    }

    @Override
    public void jobExecutionVetoed(JobExecutionContext context) {
        // Called if job was vetoed by a trigger listener
    }

    @Override
    public void jobWasExecuted(JobExecutionContext context, JobExecutionException jobException) {
        // Called after job executes — check jobException for failures
        if (jobException != null) {
            // Handle failed job
        }
    }
}

Matcher Types

The @ListeningFor annotation supports a matcher attribute and a value attribute to control which jobs the listener observes:

Registering Job Listeners

Plain Dropwizard:

Pass listeners to the JobsBundle constructor:

@Override
public void initialize(Bootstrap<MyConfiguration> bootstrap) {
    Job myJob = new MyJob();
    JobListener myListener = new MyJobListener();
    bootstrap.addBundle(new JobsBundle(List.of(myJob), List.of(myListener)));
}

Guice:

Register listeners as beans in your Guice module. The GuiceJobsBundle will auto-discover all JobListener implementations annotated with @ListeningFor:

public class MyModule extends AbstractModule {
    @Override
    protected void configure() {
        bind(MyJobListener.class).asEagerSingleton();
    }
}

Note: When using GuiceJobsBundle with frameworks like dropwizard-guicey, you may need to use the deferred constructor that accepts a Supplier<Injector>. See the Guice module documentation for details.

Spring:

Register listeners as beans in your Spring configuration. The SpringJobsBundle will auto-discover all JobListener implementations annotated with @ListeningFor:

@Configuration
public class MyConfiguration {
    @Bean
    public MyJobListener myJobListener() {
        return new MyJobListener();
    }
}

Using dropwizard-jobs in a Clustered Environment

By default, dropwizard-jobs is designed to be used with an in-memory Quartz scheduler. If you wish to deploy it in a clustered environment that consists of more than one node, you'll need to use a scheduler that has some sort of persistence. You can either add a file called quartz.properties to your classpath or you can provide the quartz configuration in your Dropwizard configuration file. The content of the quartz element is passed to the Quartz scheduler directly (so you can take the properties from the official docs). If you'd like to add the config to your Dropwizard configuration file, you need to override the getQuartzConfiguration() method in your application's configuration. You can set the map to DefaultQuartzConfiguration.get().

See the full Quartz configuration reference at https://www.quartz-scheduler.org/documentation/quartz-2.x/configuration/

[...]
quartz:
  org.quartz.scheduler.instanceName: "scheduler"
  org.quartz.scheduler.instanceId: "AUTO"
  org.quartz.scheduler.skipUpdateCheck: "true"
  org.quartz.threadPool.class: "org.quartz.simpl.SimpleThreadPool"
  org.quartz.threadPool.threadCount: "10"
  org.quartz.threadPool.threadPriority: "5"
  org.quartz.jobStore.misfireThreshold: "60000"
  org.quartz.jobStore.class: "org.quartz.impl.jdbcjobstore.JobStoreTX"
  org.quartz.jobStore.driverDelegateClass: "org.quartz.impl.jdbcjobstore.StdJDBCDelegate"
  org.quartz.jobStore.useProperties: "false"
  org.quartz.jobStore.dataSource: "myDS"
  org.quartz.jobStore.tablePrefix: "QRTZ_"
  org.quartz.jobStore.isClustered: "true"
  org.quartz.dataSource.myDS.driver: "com.mysql.cj.jdbc.Driver"
  org.quartz.dataSource.myDS.URL: "jdbc:mysql://localhost:3306/quartz"
  org.quartz.dataSource.myDS.user: "fami"
  # NOTE: Use environment variables or a secrets manager for sensitive values
  org.quartz.dataSource.myDS.password: "<YOUR_PASSWORD>"
  org.quartz.dataSource.myDS.maxConnections: "5"
  org.quartz.dataSource.myDS.validationQuery: "select 1"

When you do this, dropwizard-jobs will ensure that only one instance of each job is scheduled, regardless of the number of nodes in your cluster by using the fully-qualified class name of your job implementation as the name of your job. For example, if your job implementation resides in a class called MyJob, which in turn is located in the package com.my.awesome.web.app, then the name of your job (so far as Quartz is concerned) will be com.my.awesome.web.app.MyJob.

If you wish to override the default name that dropwizard-jobs assigns to your job, you can do so by setting the jobName property in the @Every or @On annotation like so:

package com.my.awesome.web.app

/**
 * This job will be given the name "MyJob" instead of the name "com.my.awesome.web.app.MyJob"
 */
@Every(value="5s", jobName="MyJob")
public class MyJob extends Job {
  @Override
  public void doJob(JobExecutionContext context) throws JobExecutionException {
    // do some work here
  }
}

This property is not supported in the @OnApplicationStart or @ApplicationStop annotations, as they are designed for jobs that will fire reliably when Dropwizard starts or stops your web application. As such, jobs annotated with @OnApplicationStart or @OnApplicationStop will be given unique names, and will be fired according to schedule on every node in your cluster.

Programmatic Quartz Configuration

In some cases, such as when writing integration tests with dynamic infrastructure (e.g. Testcontainers), you may need to configure Quartz properties programmatically using values that are only known at runtime. However, Dropwizard's `ConfigOverride.config()