This guide covers:
Although many examples won't make much sense without demonstrating the use of triggers, this guide will focus more on jobs and related scheduler operations, while the dedicated guide on triggers will focus more on using various kinds of schedules.
This guide covers Quartzite
Quartz separates operations that are performed (called jobs) from rules according to which they are performed (triggers). Triggers combine execution schedule (for example, "every 4 hours" or "at noon every Friday"), date/time when execution starts and ends, operation priority and a few other things.
A job may have multiple triggers associated with them (although it is common to have just one). Both jobs and triggers have identifiers (called "keys") that you use to manage them, for example, unschedule, pause or resume.
Jobs in Quartz are objects that implement
org.quartz.Job, a single function interface. One way to define a job is to define a record
that implements that interface:
This does not look very Clojuric, does it. Because jobs are single method interfaces, it makes perfect sense to use Clojure functions as jobs. Unfortunately, due to certain Quartz implementation details and the way Clojure loads generated classes, many approaches to using functions do not work.
Quartzite provides a macro that makes defining jobs more concise but avoids limitations of using proxies and reification. The macro
These examples demonstrate defining the "executable part" of a job. As we've mentioned before, to make it possible to manage jobs and triggers,
Quartz requires them to have identities. To define a complete job that can be submitted for scheduling, you use a DSL in the
clojurewerkz.quartzite.jobs/key function can be used with any other function that accepts job keys.
In order to pause or completely remove a job from the scheduler, there needs to be a way to identify it. Job identifiers are called "keys". A key consists
of a string identifier and an (optional) group. To instantiate keys, use
When group is not specified, the default group is used. It is common to use groups to "namespace" executed jobs, for example, to separate operations that perform periodic data aggregation from those that generate invoices.
Many jobs will need some kind of context to carry out their duties. For example, an aggregation job associated with a particular account will need that account's id in order to load it from a data store. A job that involves retrieving Web pages may need the URL to use and so on.
When Quartz executes a job, it will pass it a job context object that among other things, includes arbitrary data that the job needs.
Lets take a look at a simplest Quartzite job possible:
It takes the aforementioned job context which is an instance of JobExecutionContext. The job execution context you can retrieve job data map. Quartzite offers a function that returns job data map as an immutable Clojure map:
Job data is optional and can be added via the job definition DSL:
clojurewerkz.quartzite.scheduler/schedule submits a job and a trigger associated with it for execution:
If the scheduler is started, execution begins according to the start moment of the submitted trigger. In the example above, the trigger will fire 10 times every 200 ms and expire after that. Expired triggers do not execute associated jobs.
To unschedule an operation, you unschedule its trigger (or several of them) using
Please note that
unschedule-job takes a trigger key.
clojurewerkz.quartzite.scheduler/unschedule-jobs works the same way but
takes a collection of keys.
There are other functions that delete jbos and all their triggers, pause execution of triggers and so on. They are covered in the Scheduling, unscheduling and pausing jobs guide.
Jobs can be paused and resumed. Pausing a job pauses all of its triggers so the job won't be executed but is not removed from
the scheduler. To pause a single job, use
clojurewerkz.quartzite.scheduler/pause-job and pass it the job's key:
clojurewerkz.quartzite.scheduler/pause-jobs will pause one or several groups of jobs by pausing their triggers. What groups
are paused is determined by the group matcher, instantiated via Java interop:
In addition to the exact matcher, there are several other matchers available:
Resuming a job makes all its triggers fire again.
clojurewerkz.quartzite.scheduler/resume-job is the function that does
that for a single job:
clojurewerkz.quartzite.scheduler/resume-jobs resumes one or more job groups using the already covered group matchers:
clojurewerkz.quartzite.scheduler/resume-all! are functions
that pause and resume the entire scheduler. Use them carefully. Both take no arguments.
A misfire occurs if a persistent trigger "misses" its firing time because of being paused, the scheduler being shutdown, or because there are no available threads in Quartz's thread pool for executing the job. When a job is resumed, if any of its triggers have missed one or more fire-times, the trigger's misfire instruction will apply.
Misfires are covered in the triggers guide.
It is possible to completely remove a job from the scheduler. Doing so will also remove all the associated triggers. The job
will never be executed again (unless it is re-scheduled).
a single job by job key:
clojurewerkz.quartzite.scheduler/delete-jobs removes multiple jobs and takes a collection of keys:
The documentation is organized as a number of guides, covering all kinds of topics.
We recommend that you read the following guides first, if possible, in this order:
Please take a moment to tell us what you think about this guide on Twitter or the Quartzite mailing list
Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is key to making the documentation better.