Schwartz Plugin - Reference Documentation

The plugin includes an implementation of the Quartz JobFactory interface, SchwartzJobFactory, which manages retrieving Spring bean instances when triggers fire for jobs registered as Spring beans, and instantiating new instances of POGO/POJO classes otherwise. It will also make “job data” from multiple sources available to the job classes when they’re executing.

Job data has three sources, the global values stored in the Scheduler SchedulerContext, job-specific values from a JobDataMap configured for the JobDetail, and trigger-specific JobDataMap instances configured for individual triggers. When you register the job in the scheduler you can include a JobDataMap with whatever information the job needs, or none if that isn’t needed. Likewise when scheduling triggers you can store trigger-specific data. The three sources are merged together when a trigger fires and your job instance is created or retrieved as a bean, with global values added first, then the job data, and then the trigger data. This means that job and trigger can both override values from the SchedulerContext, and trigger values can override job values.

If you have setters or properties in your job class corresponding to keys in the merged data map, those values will be set for each invocation. This isn’t a requirement though, and you can always access all of the merged data from the JobExecutionContext instance that is provided for each execution (it’s the argument in the Job interface void execute(JobExecutionContext context) method that all jobs implement).

The plugin includes a trait, SchwartzJob, which you can implement to take advantage of its default settings and configuration which will make creating, registering and managing JobDetail and Trigger instances a lot simpler. By implementing the trait, QuartzService can easily create a JobDetail instance using the implementation class as the jobClass, and invoking the various getter methods defined in the trait. The initial return values have sensible default values, but you can override any of them by creating the same method in your implementation class with custom values.

The trait also implements the InterruptableJob interface and includes an empty interrupt() method that you can override for any job class that should perform some actions if they are interrupted.

Quartz requires that a Job that is stateful indicate that using two annotations, DisallowConcurrentExecution and PersistJobDataAfterExecution. You can annotate your stateful job classes with these yourself, but the plugin includes another trait, StatefulSchwartzJob, which simply extends SchwartzJob and includes these annotations. So you can just implement SchwartzJob or StatefulSchwartzJob as needed.

The trait has one abstract method, buildTriggers(), which is invoked from afterPropertiesSet() which is called by the Spring ApplicationContext if your job is a Spring bean after dependencies have been injected (because the trait implements InitializingBean). Create your job’s trigger(s) at this point and add them to the triggers list defined in the trait to have them auto-registered for you at startup. You can use the plugin’s builder support or the Quartz builders directly to create triggers. You don’t have to create any triggers though, and can just define an empty method; you can configure and schedule triggers yourself, or trigger jobs on-demand as needed.

Note that using these traits is not required - you can create (or reuse from non-Grails applications) job classes that implement the Job interface, and work directly with Quartz, creating and scheduling JobDetail and Trigger instances yourself. The traits and other helper classes are and are there to reduce the amount of manual configuration required. The plugin supports any implementation of the Job interface.

There are several configuration settings that you can set in the Grails config to customize various aspects of the plugin, and you can also specify Quartz configuration settings that will affect the configuration of the Scheduler, JobStore, etc.

All config options must be in the quartz block in application.groovy (or make the equivalent changes in application.yml if you haven’t converted it to Groovy syntax yet) but are shown here without the prefix.

In addition to the named config options above, the plugin generates a Properties instance with values that you would typically otherwise store in a quartz.properties file. Configuring the values in this way can be much more flexible, especially if you take advantage of Groovy syntax, and also has support for environments. Set the values in the properties block under in the root quartz block; when they’re read to populate the Properties instance they’re prefixed with "org.". This listing shows a fairly complete listing of the default settings for properties that are most likely to be configured. Since this mostly includes default values it doesn’t make much sense to copy this to your application’s config file - it’s here only as a reference.

Check out the Quartz configuration documentation for detailed information about what properties are available.

Triggers are defined statically in the Quartz plugin in a triggers closure in each job class, using the plugin’s trigger DSL. Only “simple” and “cron” triggers are directly supported, but you can configure any trigger type by specifying the class and all of the trigger properties as name/value pairs. The DSL is fairly limited and there is no autocompletion.

With Schwartz you also can define triggers in the job class, typically in the buildTriggers() method in job classes that implement SchwartzJob or StatefulSchwartzJob. There is no DSL, but instead you define triggers programmatically. As you can see from the examples throughout the documentation, using the Quartz builder classes added in Quartz 2.0, or the plugin’s BuilderFactory which aggregates the logic for all of the Quartz builders into one builder, the programmatic approach feels a lot like using a DSL but with the added benefit of having immediate feedback about available options and syntax when coding in an IDE. You can create different triggers or use different settings depending on the current Environment, get access to the Config, and use any Spring bean, Grails service, etc. as needed, and the QuartzService is available inside all SchwartzJob classes. You can also create instances of the “Impl” classes directly and set properties there, for example if you already have working existing code, but this approach shouldn’t be used in general.

You can additionally create triggers outside of your job classes and schedule them on-demand, using the Quartz Scheduler or helper methods in QuartzService.

When building triggers, if no value is specified the Quartz plugin defaults to a 60,000 millisecond (one minute) repeat interval, “GRAILS_JOBS” for the job group name, “GRAILS_TRIGGERS” for the trigger group name, “Grails Job” for the job description, and, inexplicably, “0 0 6 * * ?” for the CRON expression. This plugin has no defaults for these properties (other than the job and trigger names, which default to the Quartz default value of “DEFAULT” for both).

Another difference is trigger priority; triggers created in grails.plugins.quartz.TriggerUtils default to a priority value of 6 (one larger than the default value of 5, presumably as an homage to Spinal Tap).

The two plugins have the same default values for start delay (0), repeat count (repeat forever), session required (true), durability (true), and recovery requested (false).

The general flow for creating any of the four types of triggers is to start with a call to the static TriggerBuilder.newTrigger() method to create the initial TriggerBuilder instance, and then call the various instance methods to configure job detail properties and common schedule-related properties, e.g.

Using static imports can help a lot to compact your builder code, e.g.

The instance methods are designed to be chained and all mutator methods return this instead of being void; this isn’t required but is the preferred way to work with the builders, so all of the examples will use this approach. At some point in the method call chain you can join in a schedule builder with a call to withSchedule(), e.g.

The schedule builders have one or more static methods that are used to create an instance with all of the initial properties required for the particular schedule pattern. In this example I used a method that will implicitly generate a CRON expression using the three properties I provided (daily repeat, repeat hour, and repeat minute) but I could have used a different initializing method for weekly repeating, monthly, etc., or the simplest option, providing a CRON expression directly:

Once everything is configured, call build() to instantiate and configure the trigger type associated with the schedule builder you used:

The builders use generics, so in the example above no cast is needed even if your code is annotated with @CompileStatic.

The following sections describe the various initial static methods and subsequent instance methods for each of the builders

Quartz added trigger builder classes in 2.0 that have chainable methods (the mutator methods return this) and provide a fluent and intuitive approach to creating triggers. In practice I found several methods to be a bit verbose, and thought it would be better in many cases to combine all of the builders so there would be a single starting point for all types of triggers. The plugin’s BuilderFactory (an awkward name, but certainly better than BuilderBuilder …​) provides this.

If you’re building triggers inside a SchwartzJob class the best way to initialize a BuilderFactory is with one of the two builder() methods since they set the job name and group, and optionally the trigger name for you:

You can also start with just the constructor and do everything explicitly, e.g.

All of the options in the various triggers are configurable as properties or chainable methods, so the standard Groovy Map constructor is an option also, either explicitly followed by a call to the build() instance method, or in one step using the static build(Map) method, e.g.

which is equivalent to

Because all trigger properties and methods are available when using BuilderFactory, it is possible to inadvertently set properties or call methods that apply to two or more trigger types; this is invalid and when you call the build() method, the code that validates the configured properties and determines which type of trigger to build will detect the problem and throw an exception with detailed information about what values were applicable for the different trigger types to help you to fix the mistakes.

The following tables summarize the various methods and corresponding chainable methods that are available for the different trigger types, and the common non-schedule-related methods applicable to all trigger types.

Implements JobListener and logs current state information at the debug level for each method.

Implements TriggerListener and logs current state information at the debug level for each method.

Implements SchedulerListener and logs method parameter data at the debug level for each method.

Implements JobListener and logs the JobKey and the exception stacktrace if an exception occurs while a job is executing.

Implements JobListener and works like the web-tier open-session-in-view pattern, binding a GORM session before your job starts and closing it when it finishes. Will be active for each SchwartzJob only if the job class returns true from its getSessionRequired() method (defaults to true) defined in the trait.

Aggregate interface that implements JobListener, TriggerListener, and SchedulerListener. com.agileorbit.schwartz.listener.QuartzListenersAdaptor is an adaptor class that implements QuartzListeners and delegates each method to the corresponding method in an instance of JobListenerSupport, SchedulerListenerSupport, or TriggerListenerSupport.

There’s not much to do to change from in-memory job storage to database storage, but be sure to read the JDBC Job Storage section of the docs before starting this tutorial.

In this example MySQL is used but you can use any of the database types supported by Quartz. Very few details are database-specific, primarily just the initial database creation steps.

If you don’t already have a MySQL database to work with, run these commands in a MySQL client as the root user or another user with permission to create databases and grant permissions:

Be sure to read the Clustering section of the docs before starting this tutorial.

The default implementation of the Quartz JobStore is RAMJobStore which keeps everything in-memory at the server where the schedular is running. This works well when you only have one server but when you need to scale beyond one, or run multiple instances for high availability, it’s important to both spread the workload between the servers and to ensure that triggers only fire on one machine, and for that you need centralized storage. Using Quartz’s support for storage in a relational database is one good option, and Quartz also supports using Terracotta as the JobStore.

The initial configuration to change from in-memory to a database is only a few steps, and there are many optional tuning and configuration options described in the documentation.

One step when using traditional Quartz outside of Grails is deciding what transaction support to use; JobStoreTX manages transactions for Quartz table updates but cannot participate in your application’s transactions, or JobStoreCMT which uses the transaction support from the application server or framework and can update Quartz tables transactionally along with application table updates. You also would add connection and pool-management properties to the Quartz configuration to create a DataSource that Quartz uses for its queries.

Spring provides a third option with its LocalDataSourceJobStore implementation which uses the application’s DataSource (or one of them if there are multiple) and existing transaction support, which lets Quartz updates use the same transaction support as the rest of the application. This is the option used by the plugin, and to enable it you simply set the DataSource as a property of the SchedulerFactoryBean Spring bean. The plugin will do this for you if you set the quartz.jdbcStore config value to true:

By default it will use the dataSource Spring bean, and to use a different DataSource bean, set its name in the quartz.jdbcStoreDataSource property:

If you use this approach, do not configure the org.quartz.jobStore.class Quartz property or any values for a connection pool as described in the Quartz JDBC documentation - the plugin and the Spring support classes make the appropriate config changes when creating the Scheduler and its support objects.

Clustering is a moderately complex topic and you should read the Quartz clustering documentation before trying to implement it, but there are only a few required steps to get basic clustering working.

The first is to configure storage of job data in a database, so refer to the previous section for those steps.

In addition, you must enable clustering with the isClustered config setting, and choose a shared cluster name by setting the instanceName config setting, e.g.

The remaining required config setting is a unique instance id for each node in the cluster, using the instanceId config setting. You can let Quartz assign a unique name for each node automatically by using the value “AUTO”, e.g.

but if you want to choose the values yourself you would omit that setting from application.groovy and set the value externally for each server instance.

That’s all that’s required, but refer to the Quartz docs for information about the various optional config settings that are available, and try out the Cluster Tutorial to see clustering in action.

To summarize, the general steps to change job storage from in-memory to JDBC are:

Creates a new Quartz Job class. The general format is:

Creates a class with the specified class name and package that implements either SchwartzJob or StatefulSchwartzJob. By default it will create a stateless class but will make it stateful if you include the --pogo flag.

By default the class will be generated as a Grails Service under grails-app/services, but if you include the --pogo flag the class will be generated under src/main/groovy. The plugin doesn’t automatically register your job classes as Spring beans, but often job classes need to access the database or call services and other Spring beans. By making your class a Grails Service you get support for dependency injection and can easily make your job class transactional with the Transactional annotation. All beans that implement one of the traits will be auto-discovered at startup by QuartzService and a JobDetails and any configured Trigger instances will be registered in the Quartz Scheduler if they are not already.

Creates a Liquibase changelog (or the SQL generated from a changelog) to create Quartz database tables. The general format is:

Creates in-memory Liquibase model objects and builds a changelog from those in Groovy or XML format (or any format supported by Liquibase). Will optionally generate the resulting SQL from the changelog. The format is determined by the extension of the file you specify; if it is “groovy”, “xml”, or any of the file formats supported by Liquibase, a changelog file will be created. Unlike the database-migration plugin the file is not written relative to the grails-app/migrations folder, it’s written relative to the application root directory. If the extension of the file is “sql”, a changelog will be generated but it will be used to by Liquibase to generate the SQL that would be created for the changelog and that SQL is written to the output file.

The liquibase-core jar or the database-migration plugin must be in the classpath to use this command.

Uses Hibernate to generate SQL to create Quartz database tables. The general format is:

Creates in-memory Hibernate model objects and returns the SQL generated from those; this is similar to the process used by the schema-export script. The hibernate-core jar or the hibernate plugin must be in the classpath to use this command.