In addition to creating jobs defined in the deployment descriptors you can create and remove them at runtime too.
3.4.1. Scheduling Jobs at Runtime
It is possible to create a new job at runtime. You need to use the schedule method available in the TorqueBox::ScheduledJob module. This method returns true if the task is completed or false otherwise. There is a default timeout set to 30 seconds meaning that if the job will not be scheduled in the mentioned time the method will finish immediately returning false.
Jobs Management at Runtime
Example 10.6. Scheduling a job
TorqueBox::ScheduledJob.schedule('JobClassName', '*/10 * * * * ?')
This simple execution will create a new scheduled job implemented in the JobClassName class and run it every 10 seconds.
TorqueBox::ScheduledJob.schedule('JobClassName', '*/10 * * * * ?', :name => 'simple.job',
:description => 'This is a simple job', :timeout => '2s',
:config => {"number" => 1, "text" => "bacon"}, :singleton => false)
This example shows all the available options. Please see the table below for explanation.
The schedule method is executed asynchronously and returns a java.util.concurrent.CountDownLatch object which can be used to wait for the task completion. If you want to have a synchronous method use the schedule_sync method. It will block and return true after successful task completion and false otherwise.
The job class name and cron expression is required. Additionally the schedule method accepts following, optional parameters:
Table 10.1. Job scheduling options
Option Default Description
:name "default" The job name unique across the
application.
:description Job description.
:timeout "0s" The time after the job execution
should be interrupted. By default it'll never interrupt the job execution.
:config Data that should be injected to the
job constructor.
:singleton true Flag to determine if the job should
be executed on every node in the cluster or only on one node (default).
'At' Jobs
Every job requires a unique name across the application. By default, if there is no :name parameter provided the name will be set to the class name. In case the job class name includes module name, like this: Module::ClassName, the job name will be set to Module.ClassName.
If you schedule a job with a name of a job already deployed - the old job will be replaced with the new one.
Note that if you schedule a job at runtime it'll not be persisted and is lost after the server restart.
3.4.2. Removing Jobs at Runtime
You can easily remove a scheduled job. To do this use the remove method available in the TorqueBox::ScheduledJob module. This method returns true if the task is completed or false otherwise. There is a default timeout set to 30 seconds meaning that if the job will not be removed in the mentioned time the method will finish immediately returning false.
The remove method is executed asynchronously and returns a java.util.concurrent.CountDownLatch object which can be used to wait for the task completion. If you want to have a synchronous method use the remove_sync method. It will block and return true after successful task completion and false otherwise.
Example 10.7. Removing a job
TorqueBox::ScheduledJob.remove('simple.job')
This example will lookup a job with the 'simple.job' name and remove it.
Note that if you remove a job defined in the deployment descriptor, it'll be started again after server restart.
4. 'At' Jobs
'At' jobs are jobs that use different scheduling mechanism compared to regular scheduled jobs where you define the execution time with cron expressions. In case of 'at' jobs you have more control over the execution of the job.
Example 10.8. Examples of scheduling 'at' jobs
# The job will be executed every 200 ms, from now, for the next 10 seconds TorqueBox::ScheduledJob.at('SimpleJob', :every => 200, :until => Time.now + 10)
# The job will be executed for the first time in 10 seconds (current time + 10 seconds), then every
'At' Jobs
TorqueBox::ScheduledJob.at('SimpleJob', :at => Time.now + 10, :every => 500, :until => Time.now + 20)
# The job will be executed for the first time in 5s and repeated 3 times # The time between executions is set to 1.5s
TorqueBox::ScheduledJob.at('SimpleJob', :in => 5000, :repeat => 3, :every => 1500)
The at method is executed asynchronously and returns a java.util.concurrent.CountDownLatch object which can be used to wait for the task completion. If you want to have a synchronous method use the at_sync method. It will block and return true after successful task completion and false otherwise.
The first parameter of the at method is the class name of the job implementation to execute. The second parameter allows to specify when the job should be executed. Below you can find valid options. Table 10.2. 'At' job scheduling options
Option Default Description
:at Time.now Specifies when the at job should
start firing. Must be a Time class. Can't be specified with :in.
:in Specifies when the at job should
start firing, in ms from now. Can't be specified with :at.
:every Specifies the delay interval
between at job firings, in ms. If specified without a :repeat or :until, the job will fire indefinitely.
:repeat Specifies the number of times an
at job should repeat beyond its initial firing. Requires :every to be provided.
:until Specifies when the at job should
stop firing. Must be a Time class.
:name job class name The job name unique across the
application.
:description Job description.
:timeout "0s" The time after the job execution
should be interrupted. By default it'll never interrupt the job execution.
:config Data that should be injected to the
Clustered Jobs
Option Default Description
:singleton true Flag to determine if the job should
be executed on every node in the cluster or only on one node (default).