Awesome
Cronut: A Clojure Companion to Quartz
Cronut provides a data-first Clojure wrapper for the Quartz Job Scheduler
Summary
Quartz is richly featured, open source job scheduling library that is fairly standard on the JVM.
Clojure has two existing wrappers for Quartz:
How does Cronut differ?
- Configured entirely from data (with Integrant bindings provided)
- No macros or new protocols, just implement the org.quartz.Job interface
- No global Clojure state
- Latest version of Quartz
- Tagged literals to shortcut common use-cases (#cronut/cron, #cronut/interval)
- Easily extensible for further triggers / tagged literals
- Zero dependencies other than Clojure, Quartz, and Integrant
- Configurable control of concurrent job execution
Usage
:cronut/scheduler
Cronut provides lifecycle implementation for the Quartz Scheduler, exposed via Integrant / :cronut/scheduler
The scheduler supports the following fields:
- (required) :schedule - a sequence of 'items' to schedule, each being a map containing a :job and :trigger
- (optional, default false) :disallowConcurrentExecution? - run all jobs with @DisableConcurrentExecution
- (optional, default false) :update-check? check for Quartz updates on system startup.
e.g.
:cronut/scheduler {:schedule [{:job #ig/ref :test.job/two
:trigger #cronut/interval 3500}
{:job #ig/ref :test.job/two
:trigger #cronut/cron "*/8 * * * * ?"
:misfire :do-nothing}]
:disallowConcurrentExecution? true}}
Controlling Concurrent Execution
Cronut 0.2.6+ supports the option to disable concurrent execution of jobs (see configuration, above).
This flag is set at a global level and affects all scheduled jobs. Raise a PR if you want to intermingle concurrency.
If you disable concurrent job execution ensure you understand Quartz Misfire options and remember to set org.quartz.jobStore.misfireThreshold=[some ms value] in your quartz.properties file. See Quartz documentation for more information.
See our test-resources/config.edn and test-resources/org/quartz/quartz.properties for examples.
The :job
The :job in every scheduled item must implement the org.quartz.Job interface
The expectation being that every 'job' in your Integrant system will reify that interface, either directly via reify
or by returning a defrecord that implements the interface. e.g.
(defmethod ig/init-key :test.job/one
[_ config]
(reify Job
(execute [this job-context]
(log/info "Reified Impl:" config))))
(defrecord TestDefrecordJobImpl [identity description recover? durable? test-dep]
Job
(execute [this job-context]
(log/info "Defrecord Impl:" this)))
(defmethod ig/init-key :test.job/two
[_ config]
(map->TestDefrecordJobImpl config))
Cronut supports further Quartz configuration of jobs (identity, description, recovery, and priority) by expecting those values to be assoc'd onto your job. You do not have to set them (in fact in most cases you can likely ignore them), however if you do want that control you will likely use the defrecord approach as opposed to the simpler reify option and pass that configuration through edn, e.g.
:test.job/two {:identity ["job-two" "test"]
:description "test job"
:recover? true
:durable? false
:dep-one #ig/ref :dep/one
:dep-two #ig/ref :test.job/one}
The :trigger
The :trigger in every scheduled item must resolve to an org.quartz.Trigger of some variety or another, to ease that
resolution Cronut provides the following tagged literals:
Tagged Literals
#cronut/cron: Simple Cron Scheduling
A job is scheduled to run on a cron by using the #cronut/cron tagged literal followed by a valid cron expression
The job will start immediately when the system is initialized, and runs in the default system time-zone
:trigger #cronut/cron "*/8 * * * * ?"
#cronut/interval: Simple Interval Scheduling
A job is scheduled to run periodically by using the #cronut/interval tagged literal followed by a milliseconds value
:trigger #cronut/interval 3500
#cronut/trigger: Full (and extensible) Trigger Definition
Both #cronut/cron and #cronut/interval are effectively shortcuts to full trigger definition with sensible defaults.
The #cronut/trigger tagged literal supports the full set of Quartz configuration for Simple and Cron triggers:
;; interval
:trigger #cronut/trigger {:type :simple
:interval 3000
:repeat :forever
:identity ["trigger-two" "test"]
:description "sample simple trigger"
:start #inst "2019-01-01T00:00:00.000-00:00"
:end #inst "2019-02-01T00:00:00.000-00:00"
:misfire :ignore
:priority 5}
;;cron
:trigger #cronut/trigger {:type :cron
:cron "*/6 * * * * ?"
:identity ["trigger-five" "test"]
:description "sample cron trigger"
:start #inst "2018-01-01T00:00:00.000-00:00"
:end #inst "2029-02-01T00:00:00.000-00:00"
:time-zone "Australia/Melbourne"
:misfire :fire-and-proceed
:priority 4}
This tagged literal calls a Clojure multi-method that is open for extension.
You should implement the remaining two Quartz Triggers (CalendarInterval and DailyTimeInterval), create the Tagged Literal for each, and raise a PR. Go on it will be fun, open issues exist for both triggers.
Integrant
When initializing an Integrant system you will need to provide the Cronut data readers.
See: cronut/data-readers for convenience.
(def data-readers
{'cronut/trigger cronut/trigger-builder
'cronut/cron cronut/shortcut-cron
'cronut/interval cronut/shortcut-interval})
e.g.
(defn init-system
"Convenience for starting integrant systems with cronut data-readers"
([config]
(init-system config nil))
([config readers]
(ig/init (ig/read-string {:readers (merge cronut/data-readers readers)} config))))
Quartz Specifics and Remaining Todo's
Cronut supports a single Quartz Scheduler per JVM (optionally configured with quartz.properties).
The default StdScheduler is reset and re-used on each instantiation of a :cronut/scheduler.
Cron triggers default to using the system time-zone if no trigger time-zone specifically set.
Tickets are open for the following extensions (contributions warmly welcomed):
- Implement DailyTimeInterval Trigger
- Implement CalendarInverval Trigger
- Pluggable SchedulerFactory (support more than one scheduler per JVM)
Example System
Given a simple Integrant configuration of two jobs and four triggers.
Job Two executes on multiple schedules as defined by the latter three triggers.
{:test.job/one {}
:test.job/two {:identity ["job-two" "test"]
:description "test job"
:recover? true
:durable? false
:dep-two #ig/ref :test.job/one}
:cronut/scheduler {:schedule [;; basic interval
{:job #ig/ref :test.job/one
:trigger #cronut/trigger {:type :simple
:interval 2
:time-unit :seconds
:repeat :forever}}
;; shortcut interval via cronut/interval data-reader
{:job #ig/ref :test.job/two
:trigger #cronut/interval 3500}
;; basic cron
{:job #ig/ref :test.job/two
:trigger #cronut/trigger {:type :cron
:cron "*/4 * * * * ?"}}
;; shortcut cron via cronut/cron data-reader
{:job #ig/ref :test.job/two
:trigger #cronut/cron "*/8 * * * * ?"}]}}
And the associated Integrant lifecycle impl, note:
test.job/onereifies the org.quartz.Job interfacetest.job/twoinstantiates a defrecord (that allows some further quartz job configuration)
(defmethod ig/init-key :test.job/one
[_ config]
(reify Job
(execute [this job-context]
(log/info "Reified Impl:" config))))
(defrecord TestDefrecordJobImpl [identity description recover? durable? test-dep]
Job
(execute [this job-context]
(log/info "Defrecord Impl:" this)))
(defmethod ig/init-key :test.job/two
[_ config]
(map->TestDefrecordJobImpl config))
We can realise that system and run those jobs (See cronut.integration-fixture for full example):
(require '[cronut.integration-fixture :as itf])
=> nil
(itf/init-system)
=>
{:dep/one {:a 1},
:test.job/one #object[ronut.integration_fixture$eval2343$fn$reify__2345
0x2e906b8a
"cronut.integration_fixture$eval2343$fn$reify__2345@2e906b8a"],
:test.job/two #cronut.integration_fixture.TestDefrecordJobImpl{:identity ["job-two" "test"],
:description "test job",
:recover? true,
:durable? false,
:test-dep nil,
:dep-one {:a 1},
:dep-two #object[cronut.integration_fixture$eval2343$fn$reify__2345
0x2e906b8a
"cronut.integration_fixture$eval2343$fn$reify__2345@2e906b8a"]},
:cronut/scheduler #object[org.quartz.impl.StdScheduler 0x7565dd8e "org.quartz.impl.StdScheduler@7565dd8e"]}
(itf/shutdown!)
=> nil
License
Distributed under the Apache 2.0 License.
Copyright (c) Factor House