Quartz plugin allows your Grails application to schedule jobs

Quartz plugin allows your Grails application to schedule jobs to be executed using a specified interval or cron expression. The underlying system uses the Quartz Enterprise Job Scheduler configured via Spring, but is made simpler by the coding by convention paradigm.

Installation

Just execute following from your application directory:

grails install-plugin quartz

If above method is not work for some reason you can download plugin distribution from http://svn.codehaus.org/grails-plugins/grails-quartz/tags/RELEASE_0_3_3/grails-quartz-0.3.3.zip and install it with:

grails install-plugin /path/to/downloaded/plugin/distrib

Using



Scheduling Jobs

To create a new job run the "grails create-job" command and enter the name of the job. Grails will create a new job and place it in the "grails-app/jobs" directory: 

class MyJob {
  def startDelay = 60000
  def timeout = 1000

  def group = "MyGroup"

  def execute(){
    print "Job run!"
  }
}


The above example will wait for 1 minute and after that will call the 'execute' method every second. The 'timeout' and 'startDelay' properties are specified in milliseconds and must have Integer or Long type. If these properties are not specified default values are applied (1 minute for 'timeout' property and 30 seconds for 'startDelay' property). It isn't recommended to set 'startDelay' property value lesser than 30 seconds since your application needs to fully startup before executing jobs. Jobs can optionally be placed in different groups.



Scheduling a Cron Job

Jobs can be scheduled using a cron expression. For those unfamiliar with "cron", this means being able to create a firing schedule such as: "At 8:00am every Monday through Friday" or "At 1:30am every last Friday of the month". (See the API docs for the CronTrigger class in Quartz for more info on cron expressions): 

class MyJob  {
 def cronExpression = "0 0 6 * * ?"

 def group = "MyGroup"

 def execute(){
   print "Job run!"
 }
}





Multiple Triggers for a Job

Since 0.3 version you can also configure triggers in other way. With this method you can configure multiple triggers per job as well as register your custom trigger. To do this simply add static  triggers  closure to your job: 

class MyJob {
    static triggers = {
        simpleTrigger startDelay:10000, timeout: 30000, repeatCount: 10
        cronTrigger startDelay:10000, cronExpression: '0/6 * 15 * * ?'
        customTrigger triggerClass:MyTriggerClass, myParam:myValue, myAnotherParam:myAnotherValue
    }

    def execute() {
        println "Job run!"
    }
}



With this configuration job will be executed 11 times with 30 seconds interval with first run in 10 seconds after scheduler startup (simple trigger), also it'll be executed each 6 second during 15th hour (15:00:00, 15:00:06, 15:00:12, … — this configured by cron trigger) and also it'll be executed each time your custom trigger will fire.

Three kinds of triggers are supported with the following parameters: 

simpleTrigger :

startDelay  — delay (in milliseconds) between scheduler startup and first job's execution
timeout  — timeout (in milliseconds) between consecutive job's executions
repeatCount  — trigger will fire job execution  (1 + repeatCount)  times and stop after that (specify  0  here to have one-shot job)

cronTrigger :

startDelay  — delay (in milliseconds) between scheduler startup and first job's execution
cronExpression  — cron expression

customTrigger :

triggerClass  — your class which implements Trigger interface
any params needed by your trigger



Dependency Injection and Jobs

Jobs are configured for auto-wiring by name thus properties can be injected into them. To get hold of the data source you can do: 

def dataSource

Or a service class: 

def myService

The Grails application context is configured using convention so most types can be injected simply by using their property name representation (ie the first letter being lower case in the majority of cases).



Using JobExecutionContext

Since 0.3.2 you could define execute method in your job as  def execute(context){}  in this case it will be provided with Quartz's JobExecutionContext. You could obtain some information from this context (name of the trigger which fired the execution, previous execution time, next execution time and so on) as well as provide some parameters to job through  context.getMergedJobDataMap() . If your job is stateful (see section about concurrent execution below), job data in JobExecutionContext will also persist per job executions.



Configuring the plugin

Since 0.3 version plugin supports configuration file which is stored in  grails-app/conf/QuartzConfig.groovy . The syntax is the same as default Grails configuration file  Config.groovy . You could also use per-environment configuration feature (more info).

To install initial config type in the command line:  'grails install-quartz-config' .

Currently supported options: 

autoStart  — controls automatic startup of the Quartz scheduler during application bootstrap (default:  true )
jdbcStore  — set to true if you want Quartz to persist jobs in your DB (default:  false ), you'll also need to provide  quartz.properties  file and make sure that required tables exist in your db (see Clustering section below for the sample config and automatic tables creation using Hibernate)


Hibernate Sessions and Jobs

Jobs are configured by default to have Hibernate Session bounded to thread each time job is executed. This is required if you are using Hibernate code which requires open session (such as lazy loading of collections) or working with domain objects with unique persistent constraint (it uses Hibernate Session behind the scene). If you want to override this behavior (rarely useful) you can use 'sessionRequired' property: 

def sessionRequired = false




Configuring concurrent execution

By default Jobs are executed in concurrent fashion, so new Job execution can start even if previous execution of the same Job is still running. If you want to override this behavior you can use 'concurrent' property, in this case Quartz's StatefulJob will be used (you can find more info about it here): 

def concurrent = false




Clustering

Quartz plugin doesn't support clustering out-of-the-box now. However, you could use standard Quartz clustering configuration. Take a look at the example provided by Burt Beckwith: here. You'll also need to set  jdbcStore  configuration option to  true .

There are also two parameters for configuring store/clustering on jobs (  volatility  and  durability , both are  true  by default) and one for triggers ( volatility , also  true  by default). Volatile job and trigger will not persist between Quartz runs, and durable job will live even when there is no triggers referring to it.

Read Quartz documentation for more information on clustering and job stores as well as volatility and durability.



Compatibility with Grails versions

Quartz Plugin 0.3.x — tested to  work with Grails 1.0.3 Quartz Plugin 0.2 — works with Grails 0.6+

In earlier version of Grails (before 0.5.5) job sheduling with Quartz was a part of Grails core, but as of 0.5.5 it was moved out of core to this plugin. Use this plugin with Grails 0.6 or higher.



Roadmap



0.4 version (September 2008)

dynamic (programmatic) jobs scheduling
support configurable trigger listeners and job listeners
support Quartz clustering and store configuration out-of-the-box
more configuration options for QuartzConfig


Known issues

You can find a list of known issues in the JIRA