JBoss.orgCommunity Documentation

Chapter 10. TorqueBox Scheduled Jobs

10.1. What Are Scheduled Jobs?
10.2. Ruby Job Classes
10.3. Scheduling Jobs
10.3.1. Configuration Format
10.3.2. Timing Out Jobs
10.3.3. Job Concurrency
10.3.4. Jobs Management at Runtime
10.4. 'At' Jobs
10.5. Clustered Jobs
10.5.1. High Availability Singleton Jobs
10.5.2. Jobs Running on Every Node
10.6. Resource Injection with Jobs

Scheduled jobs are simply components that execute on a possibly-recurring schedule instead of in response to user interaction. Scheduled jobs fire asynchronously, outside of the normal web-browser thread-of-control. Scheduled jobs have full access to the entire Ruby environment. This allows them to interact with database models and other application functionality.

Each scheduled job maps to exactly one Ruby class. The path and filename should match the class name of the job contained in the file.

File nameClass name
mail_notifier.rbMailNotifier
mail/notifier.rbMail::Notifier


Each job class should implement a no-argument run() method to perform the work when fired. The class may optionally implement a one-argument on_error(exception) method to handle any errors raised during the job's execution.


From within the class's run() method, the full application environment is available.

The job schedule defines the time(s) that a job should execute. This may be defined to be single point in time, or more often, as recurring event. The job schedule is defined in your deployment descriptor.

Within the internal torquebox.yml descriptor (or through an external *-knob.yml descriptor), scheduled jobs are configured using the jobs: section, in which a block of information is provided for each job. The block starts with an arbitrary name for the job. Each block must also define the job class and the schedule specification. Optionally a timeout, a description, and a config may be provided. Providing a timeout will cause the job to be interrupted if it runs beyond the timeout period (see Section 10.3.2, “Timing Out Jobs”). If you provide a config, its value will be passed to the initialize method of the job class.

If you are using the DSL (via torquebox.rb) in your internal descriptor, each job is defined using the job directive, with very similar options to the YAML syntax described above. The DSL does not require a name for each job, unless you intend to share a job class across multiple jobs.


The cron attribute should contain a typical crontab-like entry. It is composed of 7 fields (6 are required).

SecondsMinutesHoursDay of MonthMonthDay of WeekYear
0-590-590-231-311-12 or JAN-DEC1-7 or SUN-SAT1970-2099 (optional)

For several fields, you may denote subdivision by using the forward-slash (/) character. To execute a job every 5 minutes, */5 in the minutes field would specify this condition.

Spans may be indicated using the dash (-) character. To execute a job Monday through Friday, MON-FRI should be used in the day-of-week field.

Multiple values may be separated using the comma (,) character. The specification of 1,15 in the day-of-month field would result in the job firing on the 1st and 15th of each month.

Either day-of-month or day-of-week must be specified using the ? character, since specifying both is contradictory.

In addition to creating jobs defined in the deployment descriptors you can create and remove them at runtime too.

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.


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:


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.

'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.


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.


If a job requires access to other resources, such as messaging topics and queues, or Java CDI components these should be injected using the resource injection facilities provided by TorqueBox (see Chapter 12, TorqueBox Resource Injection).