org.quartz.core

Interface Scheduler

All Known Implementing Classes:

QuartzScheduler

public interface Scheduler

This is the main interface of a Quartz Scheduler.

A Scheduler maintains a registry of JobDetails and Triggers. Once registered, the Scheduler is responsible for executing Job s when their associated Trigger s fire (when their scheduled time arrives).

Scheduler instances are produced by a SchedulerFactory. A scheduler that has already been created/initialized can be found and used through the same factory that produced it. After a Scheduler has been created, it is in "stand-by" mode, and must have its start() method called before it will fire any Jobs.

Job s are to be created by the 'client program', by defining a class that implements the Job interface. JobDetail objects are then created (also by the client) to define a individual instances of the Job. JobDetail instances can then be registered with the Scheduler via the scheduleJob(JobDetail, Trigger) or addJob(JobDetail, boolean) method.

Trigger s can then be defined to fire individual Job instances based on given schedules. SimpleTrigger s are most useful for one-time firings, or firing at an exact moment in time, with N repeats with a given delay between them. CronTrigger s allow scheduling based on time of day, day of week, day of month, and month of year.

Job s and Trigger s have a name and group associated with them, which should uniquely identify them within a single Scheduler. The 'group' feature may be useful for creating logical groupings or categorizations of Jobs s and Triggerss. If you don't have need for assigning a group to a given Jobs of Triggers, then you can use the DEFAULT_GROUP constant defined on this interface.

Stored Job s can also be 'manually' triggered through the use of the triggerJob(String jobName, String jobGroup) function.

Client programs may also be interested in the 'listener' interfaces that are available from Quartz. The JobListener interface provides notifications of Job executions. The TriggerListener interface provides notifications of Trigger firings. The SchedulerListener interface provides notifications of Scheduler events and errors. Listeners can be associated with local schedulers through the ListenerManager interface.

The setup/configuration of a Scheduler instance is very customizable. Please consult the documentation distributed with Quartz.

Author:

James House, Sharada Jambula

Method Summary

Modifier and Type	Method and Description
void	addJob(JobDetail jobDetail) Add the given Job to the Scheduler - with no associated Trigger.
void	deleteJob(String jobKey) Delete the identified Job from the Scheduler - and any associated Triggers.
CascadingClassLoadHelper	getCascadingClassLoadHelper()
List<JobExecutionContext>	getCurrentlyExecutingJobs() Return a list of JobExecutionContext objects that represent all currently executing Jobs in this Scheduler instance.
JobDetail	getJobDetail(String jobKey) Get the JobDetail for the Job instance with the given key.
Set<String>	getJobKeys() Get the keys of all the JobDetails in the matching groups.
ListenerManager	getListenerManager() Get a reference to the scheduler's ListenerManager, through which listeners may be registered.
Trigger	getTrigger(String triggerKey) Get the Trigger instance with the given key.
List<Trigger>	getTriggersOfJob(String jobKey) Get all Trigger s that are associated with the identified JobDetail.
boolean	isInStandbyMode() Reports whether the Scheduler is in stand-by mode.
boolean	isShutdown() Reports whether the Scheduler has been shutdown.
boolean	isStarted() Whether the scheduler has been started.
Date	rescheduleJob(String triggerName, OperableTrigger newTrigger) Remove (delete) the OperableTrigger with the given key, and store the new given one - which must be associated with the same job (the new trigger must have the job name specified) - however, the new trigger need not have the same name as the old trigger.
Date	scheduleJob(JobDetail jobDetail, OperableTrigger trigger) Add the given JobDetail to the Scheduler, and associate the given OperableTrigger with it.
Date	scheduleJob(OperableTrigger trigger) Schedule the given OperableTrigger with the Job identified by the Trigger's settings.
void	setJobFactory(JobFactory factory) Set the JobFactory that will be responsible for producing instances of Job classes.
void	shutdown(boolean waitForJobsToComplete) Halts the Scheduler's firing of Triggers, and cleans up all resources associated with the Scheduler.
void	standby() Temporarily halts the Scheduler's firing of Triggers.
void	start() Starts the Scheduler's threads that fire Triggers.
void	startDelayed(int seconds) Calls {#start()} after the indicated number of seconds.
void	triggerJob(String jobKey, JobDataMap data) Trigger the identified JobDetail (execute it now).
void	unscheduleJob(String triggerKey) Remove the indicated Trigger from the scheduler.

Method Detail

start

void start()
    throws SchedulerException

Starts the Scheduler's threads that fire Triggers. When a scheduler is first created it is in "stand-by" mode, and will not fire triggers. The scheduler can also be put into stand-by mode by calling the standby() method.

The misfire/recovery process will be started, if it is the initial call to this method on this scheduler instance.

Throws:

SchedulerException - if shutdown() has been called, or there is an error within the Scheduler.

startDelayed

void startDelayed(int seconds)
           throws SchedulerException

Calls {#start()} after the indicated number of seconds. (This call does not block). This can be useful within applications that have initializers that create the scheduler immediately, before the resources needed by the executing jobs have been fully initialized.

Throws:

SchedulerException - if shutdown() has been called, or there is an error within the Scheduler.

isStarted

boolean isStarted()
           throws SchedulerException

Whether the scheduler has been started.

Note: This only reflects whether start() has ever been called on this Scheduler, so it will return true even if the Scheduler is currently in standby mode or has been since shutdown.

Throws:

SchedulerException

standby

void standby()
      throws SchedulerException

Temporarily halts the Scheduler's firing of Triggers.

When start() is called (to bring the scheduler out of stand-by mode), trigger misfire instructions will NOT be applied during the execution of the start() method - any misfires will be detected immediately afterward (by the JobStore's normal process).

The scheduler is not destroyed, and can be re-started at any time.

Throws:

SchedulerException

isInStandbyMode

boolean isInStandbyMode()
                 throws SchedulerException

Reports whether the Scheduler is in stand-by mode.

Throws:

SchedulerException

shutdown

void shutdown(boolean waitForJobsToComplete)
       throws SchedulerException

Halts the Scheduler's firing of Triggers, and cleans up all resources associated with the Scheduler.

The scheduler cannot be re-started.

Parameters:

waitForJobsToComplete - if true the scheduler will not allow this method to return until all currently executing jobs have completed.

Throws:

SchedulerException

isShutdown

boolean isShutdown()
            throws SchedulerException

Reports whether the Scheduler has been shutdown.

Throws:

SchedulerException

getCurrentlyExecutingJobs

List<JobExecutionContext> getCurrentlyExecutingJobs()
                                             throws SchedulerException

Return a list of JobExecutionContext objects that represent all currently executing Jobs in this Scheduler instance.

This method is not cluster aware. That is, it will only return Jobs currently executing in this Scheduler instance, not across the entire cluster.

Note that the list returned is an 'instantaneous' snap-shot, and that as soon as it's returned, the true list of executing jobs may be different. Also please read the doc associated with JobExecutionContext- especially if you're using RMI.

Throws:

SchedulerException

getJobKeys

Set<String> getJobKeys()
                throws SchedulerException

Get the keys of all the JobDetails in the matching groups.

Parameters:

matcher - Matcher to evaluate against known groups

Returns:

Set of all keys matching

Throws:

SchedulerException - On error

setJobFactory

void setJobFactory(JobFactory factory)
            throws SchedulerException

Set the JobFactory that will be responsible for producing instances of Job classes.

JobFactories may be of use to those wishing to have their application produce Job instances via some special mechanism, such as to give the opportunity for dependency injection.

Throws:

SchedulerException

See Also:

org.quartz.spi.JobFactory

getListenerManager

ListenerManager getListenerManager()
                            throws SchedulerException

Get a reference to the scheduler's ListenerManager, through which listeners may be registered.

Returns:

the scheduler's ListenerManager

Throws:

SchedulerException - if the scheduler is not local

scheduleJob

Date scheduleJob(JobDetail jobDetail,
                 OperableTrigger trigger)
          throws SchedulerException

Add the given JobDetail to the Scheduler, and associate the given OperableTrigger with it.

If the given Trigger does not reference any Job, then it will be set to reference the Job passed with it into this method.

Throws:

SchedulerException - if the Job or Trigger cannot be added to the Scheduler, or there is an internal Scheduler error.

scheduleJob

Date scheduleJob(OperableTrigger trigger)
          throws SchedulerException

Schedule the given OperableTrigger with the Job identified by the Trigger's settings.

Throws:

SchedulerException - if the indicated Job does not exist, or the Trigger cannot be added to the Scheduler, or there is an internal Scheduler error.

rescheduleJob

Date rescheduleJob(String triggerName,
                   OperableTrigger newTrigger)
            throws SchedulerException

Remove (delete) the OperableTrigger with the given key, and store the new given one - which must be associated with the same job (the new trigger must have the job name specified) - however, the new trigger need not have the same name as the old trigger.

Parameters:

triggerName - identity of the trigger to replace

newTrigger - The new Trigger to be stored.

Returns:

null if a Trigger with the given name & group was not found and removed from the store, otherwise the first fire time of the newly scheduled trigger.

Throws:

SchedulerException

addJob

void addJob(JobDetail jobDetail)
     throws SchedulerException

Add the given Job to the Scheduler - with no associated Trigger. The Job will be 'dormant' until it is scheduled with a Trigger, or Scheduler.triggerJob() is called for it.

The Job must by definition be 'durable', if it is not, SchedulerException will be thrown.

Throws:

SchedulerException - if there is an internal Scheduler error, or if the Job is not durable, or a Job with the same name already exists, and replace is false.

triggerJob

void triggerJob(String jobKey,
                JobDataMap data)
         throws SchedulerException

Trigger the identified JobDetail (execute it now).

Parameters:

data - the (possibly null) JobDataMap to be associated with the trigger that fires the job immediately.

Throws:

SchedulerException

getTriggersOfJob

List<Trigger> getTriggersOfJob(String jobKey)
                        throws SchedulerException

Get all Trigger s that are associated with the identified JobDetail.

The returned Trigger objects will be snap-shots of the actual stored triggers. If you wish to modify a trigger, you must re-store the trigger afterward (e.g. see #rescheduleJob(TriggerKey, Trigger)).

Throws:

SchedulerException

getJobDetail

JobDetail getJobDetail(String jobKey)
                throws SchedulerException

Get the JobDetail for the Job instance with the given key.

The returned JobDetail object will be a snap-shot of the actual stored JobDetail. If you wish to modify the JobDetail, you must re-store the JobDetail afterward (e.g. see #addJob(JobDetail, boolean)).

Throws:

SchedulerException

getTrigger

Trigger getTrigger(String triggerKey)
            throws SchedulerException

Get the Trigger instance with the given key.

The returned Trigger object will be a snap-shot of the actual stored trigger. If you wish to modify the trigger, you must re-store the trigger afterward (e.g. see #rescheduleJob(TriggerKey, Trigger)).

Throws:

SchedulerException

deleteJob

void deleteJob(String jobKey)
        throws SchedulerException

Delete the identified Job from the Scheduler - and any associated Triggers.

Throws:

SchedulerException - if there is an internal Scheduler error.

unscheduleJob

void unscheduleJob(String triggerKey)
            throws SchedulerException

Remove the indicated Trigger from the scheduler.

If the related job does not have any other triggers, and the job is not durable, then the job will also be deleted.

Throws:

SchedulerException

getCascadingClassLoadHelper

CascadingClassLoadHelper getCascadingClassLoadHelper()