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.4. Clustered Jobs
10.4.1. High Availability Singleton Jobs
10.4.2. Jobs Running on Every Node
10.5. 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

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.

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

In order for resource injection to function with scheduled jobs, they must reside either at the root of your application directory (typical for simple Rack applications), or underneath an app/jobs/ directory. If you place the job anywhere else, it may still function, but resources injection will not be available.