Grails-Quartz 0.4.1 is the current stable version. Grails-Quartz 0.4.2 is the latest development snapshot.

See JIRA for known issues.

See GitHub project page for the latest sources.

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 {
  static triggers = {
    simple name: 'mySimpleTrigger', startDelay: 60000, repeatInterval: 1000  
  }
  def group = "MyGroup"
  def execute(){
    print "Job run!"
  }
}

By default, jobs will not be executed when running under the test environment.

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  {
  static triggers = {
    cron name: 'myTrigger', cronExpression: "0 0 6 * * ?"
  }
 def group = "MyGroup"
 def execute(){
   print "Job run!"
 }
}

Multiple Triggers for a Job

You can also configure multiple triggers per job as well as register your custom trigger.

class MyJob {
    static triggers = {
        simple name:'simpleTrigger', startDelay:10000, repeatInterval: 30000, repeatCount: 10
        cron name:'cronTrigger', startDelay:10000, cronExpression: '0/6 * 15 * * ?'
        custom name:'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:

• simple :
• name — the name that identifies the trigger
• startDelay — delay (in milliseconds) between scheduler startup and first job's execution
• repeatInterval — 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 or -1 to repeat job executions indefinitely)
• cron :
• name — the name that identifies the trigger
• startDelay — delay (in milliseconds) between scheduler startup and first job's execution
• cronExpression — cron expression
• custom :
• triggerClass — your class which implements Trigger interface
• any params needed by your trigger

Dynamic Jobs Scheduling

Starting from 0.4.1 version you have the ability to schedule job executions dynamically.

These methods are available:

• MyJob.schedule(String cronExpression, Map params?) — creates cron trigger;
• MyJob.schedule(Long repeatInterval, Integer repeatCount?, Map params?) — creates simple trigger: repeats job repeatCount+1 times with delay of repeatInterval milliseconds;
• MyJob.schedule(Date scheduleDate, Map params?) — schedules one job execution to the specific date;
• MyJob.schedule(Trigger trigger) — schedules job's execution with a custom trigger;
• MyJob.triggerNow(Map params?) — force immediate execution of the job.

class MyJob { 
  …
  def execute(context) {
    println context.mergedJobDataMap.get('foo')
  }
  …
}
// now in your controller (or service, or something else):
MyJob.triggerNow([foo:"It Works!"])

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

def myService

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 have an initial Quartz config file generated for you, type the following in the command line: 'grails install-quartz-config' . This will generate a file that looks like this:

quartz {
    autoStartup = true
    jdbcStore = false
}
environments {
    test {
        quartz {
            autoStartup = false
        }
    }
}

Currently supported options:

• autoStartup — 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)

Logging

A log is auto-injected into your task Job class without having to enable it. To set the logging level, just add something like this to your grails-app/conf/Config.groovy log4j configuration.

debug 'grails.app.task'

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: Quartz Plugin clustering_sample.tar.gz. 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.4.x — tested to work with Grails 1.1 and Grails 1.1.1

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.5 version (December 2009)

• 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