org.quartz
Interface Scheduler

All Known Implementing Classes:

RemoteScheduler, StdScheduler

public interface Scheduler

This is the main interface of a Quartz Scheduler.

A Scheduler maintains a registery of JobDetails and Triggers. Once registered, the Scheduler is responible for executing Jobs when their associated Triggers 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 must have its start() method called before it will fire any Jobs.

Jobs are to be created by the 'client program', by defining a class that implements the JobDetail 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.

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

Jobs and Triggers 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 Jobss 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 Jobs 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.

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

Author:

James House, Sharada Jambula

See Also:

Job, JobDetail, Trigger, JobListener, TriggerListener, SchedulerListener

Field Summary

static java.lang.String	DEFAULT_FAIL_OVER_GROUP A constant Trigger group name used internally by the scheduler - clients should not use the value of this constant ("FAILED_OVER_JOBS") for thename of a Trigger's group.
static java.lang.String	DEFAULT_GROUP A (possibly) usefull constant that can be used for specifying the group that Job and Trigger instances belong to.
static java.lang.String	DEFAULT_MANUAL_TRIGGERS A constant Trigger group name used internally by the scheduler - clients should not use the value of this constant ("MANUAL_TRIGGER") for thename of a Trigger's group.
static java.lang.String	DEFAULT_RECOVERY_GROUP A constant Trigger group name used internally by the scheduler - clients should not use the value of this constant ("RECOVERING_JOBS") for thename of a Trigger's group.

Method Summary

void	addCalendar(java.lang.String calName, Calendar calendar, boolean replace) Add (register) the given Calendar to the Scheduler.
void	addGlobalJobListener(JobListener jobListener) Add the given JobListener to the Scheduler's global list.
void	addGlobalTriggerListener(TriggerListener triggerListener) Add the given TriggerListener to the Scheduler's global list.
void	addJob(JobDetail jobDetail, boolean replace) Add the given Job to the Scheduler - with no associated Trigger.
void	addJobListener(JobListener jobListener) Add the given JobListener to the Scheduler's list, of registered JobListeners.
void	addSchedulerListener(SchedulerListener schedulerListener) Register the given SchedulerListener with the Scheduler.
void	addTriggerListener(TriggerListener triggerListener) Add the given TriggerListener to the Scheduler's list, of registered TriggerListeners.
boolean	deleteCalendar(java.lang.String calName) Delete the identified Calendar from the Scheduler.
boolean	deleteJob(java.lang.String jobName, java.lang.String groupName) Delete the identified Job from the Scheduler - and any associated Triggers.
Calendar	getCalendar(java.lang.String calName) Get the Calendar instance with the given name.
java.lang.String[]	getCalendarNames() Get the names of all registered Calendars.
SchedulerContext	getContext() Returns the SchedulerContext of the Scheduler.
java.util.List	getCurrentlyExecutingJobs() Return a list of JobExecutionContext objects that represent all currently executing Jobs.
java.util.List	getGlobalJobListeners() Get a List containing all of the JobListeners in the Scheduler's global list.
java.util.List	getGlobalTriggerListeners() Get a List containing all of the TriggerListeners in the Scheduler's global list.
JobDetail	getJobDetail(java.lang.String jobName, java.lang.String jobGroup) Get the JobDetail for the Job instance with the given name and group.
java.lang.String[]	getJobGroupNames() Get the names of all known JobDetail groups.
JobListener	getJobListener(java.lang.String name) Get the non-global JobListener that has the given name.
java.util.Set	getJobListenerNames() Get a Set containing the names of all the non-global JobListeners registered with the Scheduler.
java.lang.String[]	getJobNames(java.lang.String groupName) Get the names of all the JobDetails in the given group.
SchedulerMetaData	getMetaData() Get a SchedulerMetaData object describiing the settings and capabilities of the scheduler instance.
java.lang.String	getSchedulerInstanceId() Returns the instance Id of the Scheduler.
java.util.List	getSchedulerListeners() Get a List containing all of the SchedulerListeners registered with the Scheduler.
java.lang.String	getSchedulerName() Returns the name of the Scheduler.
Trigger	getTrigger(java.lang.String triggerName, java.lang.String triggerGroup) Get the Trigger instance with the given name and group.
java.lang.String[]	getTriggerGroupNames() Get the names of all known Trigger groups.
TriggerListener	getTriggerListener(java.lang.String name) Get the non-global TriggerListener that has the given name.
java.util.Set	getTriggerListenerNames() Get a Set containing the names of all the non-global TriggerListeners registered with the Scheduler.
java.lang.String[]	getTriggerNames(java.lang.String groupName) Get the names of all the Triggers in the given group.
Trigger[]	getTriggersOfJob(java.lang.String jobName, java.lang.String groupName) Get all Triggers that are associated with the identified JobDetail.
int	getTriggerState(java.lang.String triggerName, java.lang.String triggerGroup) Get the current state of the identified Trigger.
boolean	isPaused() Reports whether the Scheduler is paused.
boolean	isShutdown() Reports whether the Scheduler has been shutdown.
void	pause() Temporarily halts the Scheduler's firing of Triggers.
void	pauseAll() Pause all triggers - equivalent of calling pauseTriggerGroup(group) on every group.
void	pauseJob(java.lang.String jobName, java.lang.String groupName) Pause the JobDetail with the given name - by pausing all of its current Triggers.
void	pauseJobGroup(java.lang.String groupName) Pause all of the JobDetails in the given group - by pausing all of their Triggers.
void	pauseTrigger(java.lang.String triggerName, java.lang.String groupName) Pause the Trigger with the given name.
void	pauseTriggerGroup(java.lang.String groupName) Pause all of the Triggers in the given group.
boolean	removeGlobalJobListener(JobListener jobListener) Remove the given JobListener from the Scheduler's list of global listeners.
boolean	removeGlobalTriggerListener(TriggerListener triggerListener) Remove the given TriggerListener from the Scheduler's list of global listeners.
boolean	removeJobListener(java.lang.String name) Remove the identifed JobListener from the Scheduler's list of registered listeners.
boolean	removeSchedulerListener(SchedulerListener schedulerListener) Remove the given SchedulerListener from the Scheduler.
boolean	removeTriggerListener(java.lang.String name) Remove the identifed TriggerListener from the Scheduler's list of registered listeners.
void	resumeAll() Resume (un-pause) all triggers - equivalent of calling resumeTriggerGroup(group) on every group.
void	resumeJob(java.lang.String jobName, java.lang.String groupName) Resume (un-pause) the JobDetail with the given name.
void	resumeJobGroup(java.lang.String groupName) Resume (un-pause) all of the JobDetails in the given group.
void	resumeTrigger(java.lang.String triggerName, java.lang.String groupName) Resume (un-pause) the Trigger with the given name.
void	resumeTriggerGroup(java.lang.String groupName) Resume (un-pause) all of the Triggers in the given group.
java.util.Date	scheduleJob(JobDetail jobDetail, Trigger trigger) Add the given JobDetail to the Scheduler, and associate the given Trigger with it.
java.util.Date	scheduleJob(Trigger trigger) Schedule the given Trigger with the Job identified by the Trigger's settings.
void	shutdown() Halts the Scheduler's firing of Triggers, and cleans up all resources associated with the Scheduler.
void	shutdown(boolean waitForJobsToComplete) Halts the Scheduler's firing of Triggers, and cleans up all resources associated with the Scheduler.
void	start() Starts the Scheduler's threads that fire Triggers.
void	triggerJob(java.lang.String jobName, java.lang.String groupName) Trigger the identified JobDetail (execute it now) - the generated trigger will be non-volatile.
void	triggerJobWithVolatileTrigger(java.lang.String jobName, java.lang.String groupName) Trigger the identified JobDetail (execute it now) - the generated trigger will be volatile.
boolean	unscheduleJob(java.lang.String triggerName, java.lang.String groupName) Remove the indicated Trigger from the scheduler.

Field Detail

DEFAULT_GROUP

public static final java.lang.String DEFAULT_GROUP

A (possibly) usefull constant that can be used for specifying the group that Job and Trigger instances belong to.

See Also:

Constant Field Values

DEFAULT_MANUAL_TRIGGERS

public static final java.lang.String DEFAULT_MANUAL_TRIGGERS

A constant Trigger group name used internally by the scheduler - clients should not use the value of this constant ("MANUAL_TRIGGER") for thename of a Trigger's group.

See Also:

Constant Field Values

DEFAULT_RECOVERY_GROUP

public static final java.lang.String DEFAULT_RECOVERY_GROUP

A constant Trigger group name used internally by the scheduler - clients should not use the value of this constant ("RECOVERING_JOBS") for thename of a Trigger's group.

See Also:

Constant Field Values

DEFAULT_FAIL_OVER_GROUP

public static final java.lang.String DEFAULT_FAIL_OVER_GROUP

A constant Trigger group name used internally by the scheduler - clients should not use the value of this constant ("FAILED_OVER_JOBS") for thename of a Trigger's group.

See Also:

Constant Field Values

Method Detail

getSchedulerName

public java.lang.String getSchedulerName()
                                  throws SchedulerException

Returns the name of the Scheduler.

Throws:

SchedulerException

getSchedulerInstanceId

public java.lang.String getSchedulerInstanceId()
                                        throws SchedulerException

Returns the instance Id of the Scheduler.

Throws:

SchedulerException

getContext

public SchedulerContext getContext()
                            throws SchedulerException

Returns the SchedulerContext of the Scheduler.

Throws:

SchedulerException

start

public void start()
           throws SchedulerException

Starts the Scheduler's threads that fire Triggers.

All Triggers that have misfired will be passed to the appropriate TriggerListener(s).

Throws:

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

See Also:

pause(), shutdown()

pause

public void pause()
           throws SchedulerException

Temporarily halts the Scheduler's firing of Triggers.

When start() is called (to un-pause), trigger misfire instructions will NOT be applied.

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

Throws:

SchedulerException

See Also:

start(), pauseAll()

isPaused

public boolean isPaused()
                 throws SchedulerException

Reports whether the Scheduler is paused.

Throws:

SchedulerException

shutdown

public void shutdown()
              throws SchedulerException

Halts the Scheduler's firing of Triggers, and cleans up all resources associated with the Scheduler. Equivalent to shutdown(false).

The scheduler cannot be re-started.

Throws:

SchedulerException

See Also:

shutdown(boolean)

shutdown

public 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

See Also:

shutdown()

isShutdown

public boolean isShutdown()
                   throws SchedulerException

Reports whether the Scheduler has been shutdown.

Throws:

SchedulerException

getMetaData

public SchedulerMetaData getMetaData()
                              throws SchedulerException

Get a SchedulerMetaData object describiing the settings and capabilities of the scheduler instance.

Note that the data returned is an 'instantaneous' snap-shot, and that as soon as it's returned, the meta data values may be different.

Throws:

SchedulerException

getCurrentlyExecutingJobs

public java.util.List getCurrentlyExecutingJobs()
                                         throws SchedulerException

Return a list of JobExecutionContext objects that represent all currently executing Jobs.

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

See Also:

JobExecutionContext

scheduleJob

public java.util.Date scheduleJob(JobDetail jobDetail,
                                  Trigger trigger)
                           throws SchedulerException

Add the given JobDetail to the Scheduler, and associate the given Trigger 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

public java.util.Date scheduleJob(Trigger trigger)
                           throws SchedulerException

Schedule the given Trigger 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.

unscheduleJob

public boolean unscheduleJob(java.lang.String triggerName,
                             java.lang.String groupName)
                      throws SchedulerException

Remove the indicated Trigger from the scheduler.

Throws:

SchedulerException

addJob

public void addJob(JobDetail jobDetail,
                   boolean replace)
            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.

deleteJob

public boolean deleteJob(java.lang.String jobName,
                         java.lang.String groupName)
                  throws SchedulerException

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

Returns:

true if the Job was found and deleted.

Throws:

SchedulerException - if there is an internal Scheduler error.

triggerJob

public void triggerJob(java.lang.String jobName,
                       java.lang.String groupName)
                throws SchedulerException

Trigger the identified JobDetail (execute it now) - the generated trigger will be non-volatile.

Throws:

SchedulerException

triggerJobWithVolatileTrigger

public void triggerJobWithVolatileTrigger(java.lang.String jobName,
                                          java.lang.String groupName)
                                   throws SchedulerException

Trigger the identified JobDetail (execute it now) - the generated trigger will be volatile.

Throws:

SchedulerException

pauseJob

public void pauseJob(java.lang.String jobName,
                     java.lang.String groupName)
              throws SchedulerException

Pause the JobDetail with the given name - by pausing all of its current Triggers.

Throws:

SchedulerException

See Also:

resumeJob(String, String)

pauseJobGroup

public void pauseJobGroup(java.lang.String groupName)
                   throws SchedulerException

Pause all of the JobDetails in the given group - by pausing all of their Triggers.

The Scheduler will "remember" that the group is paused, and impose the pause on any new jobs that are added to the group while the group is paused.

Throws:

SchedulerException

See Also:

resumeJobGroup(String)

pauseTrigger

public void pauseTrigger(java.lang.String triggerName,
                         java.lang.String groupName)
                  throws SchedulerException

Pause the Trigger with the given name.

Throws:

SchedulerException

See Also:

resumeTrigger(String, String)

pauseTriggerGroup

public void pauseTriggerGroup(java.lang.String groupName)
                       throws SchedulerException

Pause all of the Triggers in the given group.

The Scheduler will "remember" that the group is paused, and impose the pause on any new triggers that are added to the group while the group is paused.

Throws:

SchedulerException

See Also:

resumeTriggerGroup(String)

resumeJob

public void resumeJob(java.lang.String jobName,
                      java.lang.String groupName)
               throws SchedulerException

Resume (un-pause) the JobDetail with the given name.

If any of the Job's Triggers missed one or more fire-times, then the Trigger's misfire instruction will be applied.

Throws:

SchedulerException

See Also:

pauseJob(String, String)

resumeJobGroup

public void resumeJobGroup(java.lang.String groupName)
                    throws SchedulerException

Resume (un-pause) all of the JobDetails in the given group.

If any of the Jobs had Triggers that missed one or more fire-times, then the Trigger's misfire instruction will be applied.

Throws:

SchedulerException

See Also:

pauseJobGroup(String)

resumeTrigger

public void resumeTrigger(java.lang.String triggerName,
                          java.lang.String groupName)
                   throws SchedulerException

Resume (un-pause) the Trigger with the given name.

If the Trigger missed one or more fire-times, then the Trigger's misfire instruction will be applied.

Throws:

SchedulerException

See Also:

pauseTrigger(String, String)

resumeTriggerGroup

public void resumeTriggerGroup(java.lang.String groupName)
                        throws SchedulerException

Resume (un-pause) all of the Triggers in the given group.

If any Trigger missed one or more fire-times, then the Trigger's misfire instruction will be applied.

Throws:

SchedulerException

See Also:

pauseTriggerGroup(String)

pauseAll

public void pauseAll()
              throws SchedulerException

Pause all triggers - equivalent of calling pauseTriggerGroup(group) on every group.

When resumeAll() is called (to un-pause), trigger misfire instructions WILL be applied.

Throws:

SchedulerException

See Also:

resumeAll(), pauseTriggerGroup(String), pause()

resumeAll

public void resumeAll()
               throws SchedulerException

Resume (un-pause) all triggers - equivalent of calling resumeTriggerGroup(group) on every group.

If any Trigger missed one or more fire-times, then the Trigger's misfire instruction will be applied.

Throws:

SchedulerException

See Also:

pauseAll()

getJobGroupNames

public java.lang.String[] getJobGroupNames()
                                    throws SchedulerException

Get the names of all known JobDetail groups.

Throws:

SchedulerException

getJobNames

public java.lang.String[] getJobNames(java.lang.String groupName)
                               throws SchedulerException

Get the names of all the JobDetails in the given group.

Throws:

SchedulerException

getTriggersOfJob

public Trigger[] getTriggersOfJob(java.lang.String jobName,
                                  java.lang.String groupName)
                           throws SchedulerException

Get all Triggers that are associated with the identified JobDetail.

Throws:

SchedulerException

getTriggerGroupNames

public java.lang.String[] getTriggerGroupNames()
                                        throws SchedulerException

Get the names of all known Trigger groups.

Throws:

SchedulerException

getTriggerNames

public java.lang.String[] getTriggerNames(java.lang.String groupName)
                                   throws SchedulerException

Get the names of all the Triggers in the given group.

Throws:

SchedulerException

getJobDetail

public JobDetail getJobDetail(java.lang.String jobName,
                              java.lang.String jobGroup)
                       throws SchedulerException

Get the JobDetail for the Job instance with the given name and group.

Throws:

SchedulerException

getTrigger

public Trigger getTrigger(java.lang.String triggerName,
                          java.lang.String triggerGroup)
                   throws SchedulerException

Get the Trigger instance with the given name and group.

Throws:

SchedulerException

getTriggerState

public int getTriggerState(java.lang.String triggerName,
                           java.lang.String triggerGroup)
                    throws SchedulerException

Get the current state of the identified Trigger.

Throws:

SchedulerException

See Also:

Trigger.STATE_NORMAL, Trigger.STATE_PAUSED, Trigger.STATE_COMPLETE, Trigger.STATE_ERROR, Trigger.STATE_NONE

addCalendar

public void addCalendar(java.lang.String calName,
                        Calendar calendar,
                        boolean replace)
                 throws SchedulerException

Add (register) the given Calendar to the Scheduler.

Throws:

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

deleteCalendar

public boolean deleteCalendar(java.lang.String calName)
                       throws SchedulerException

Delete the identified Calendar from the Scheduler.

Returns:

true if the Calendar was found and deleted.

Throws:

SchedulerException - if there is an internal Scheduler error.

getCalendar

public Calendar getCalendar(java.lang.String calName)
                     throws SchedulerException

Get the Calendar instance with the given name.

Throws:

SchedulerException

getCalendarNames

public java.lang.String[] getCalendarNames()
                                    throws SchedulerException

Get the names of all registered Calendars.

Throws:

SchedulerException

addGlobalJobListener

public void addGlobalJobListener(JobListener jobListener)
                          throws SchedulerException

Add the given JobListener to the Scheduler's global list.

Listeners in the 'global' list receive notification of execution events for ALL JobDetails.

Throws:

SchedulerException

addJobListener

public void addJobListener(JobListener jobListener)
                    throws SchedulerException

Add the given JobListener to the Scheduler's list, of registered JobListeners.

Throws:

SchedulerException

removeGlobalJobListener

public boolean removeGlobalJobListener(JobListener jobListener)
                                throws SchedulerException

Remove the given JobListener from the Scheduler's list of global listeners.

Returns:

true if the identifed listener was found in the list, and removed.

Throws:

SchedulerException

removeJobListener

public boolean removeJobListener(java.lang.String name)
                          throws SchedulerException

Remove the identifed JobListener from the Scheduler's list of registered listeners.

Returns:

true if the identifed listener was found in the list, and removed.

Throws:

SchedulerException

getGlobalJobListeners

public java.util.List getGlobalJobListeners()
                                     throws SchedulerException

Get a List containing all of the JobListeners in the Scheduler's global list.

Throws:

SchedulerException

getJobListenerNames

public java.util.Set getJobListenerNames()
                                  throws SchedulerException

Get a Set containing the names of all the non-global JobListeners registered with the Scheduler.

Throws:

SchedulerException

getJobListener

public JobListener getJobListener(java.lang.String name)
                           throws SchedulerException

Get the non-global JobListener that has the given name.

Throws:

SchedulerException

addGlobalTriggerListener

public void addGlobalTriggerListener(TriggerListener triggerListener)
                              throws SchedulerException

Add the given TriggerListener to the Scheduler's global list.

Listeners in the 'global' list receive notification of execution events for ALL Triggers.

Throws:

SchedulerException

addTriggerListener

public void addTriggerListener(TriggerListener triggerListener)
                        throws SchedulerException

Add the given TriggerListener to the Scheduler's list, of registered TriggerListeners.

Throws:

SchedulerException

removeGlobalTriggerListener

public boolean removeGlobalTriggerListener(TriggerListener triggerListener)
                                    throws SchedulerException

Remove the given TriggerListener from the Scheduler's list of global listeners.

Returns:

true if the identifed listener was found in the list, and removed.

Throws:

SchedulerException

removeTriggerListener

public boolean removeTriggerListener(java.lang.String name)
                              throws SchedulerException

Remove the identifed TriggerListener from the Scheduler's list of registered listeners.

Returns:

true if the identifed listener was found in the list, and removed.

Throws:

SchedulerException

getGlobalTriggerListeners

public java.util.List getGlobalTriggerListeners()
                                         throws SchedulerException

Get a List containing all of the TriggerListeners in the Scheduler's global list.

Throws:

SchedulerException

getTriggerListenerNames

public java.util.Set getTriggerListenerNames()
                                      throws SchedulerException

Get a Set containing the names of all the non-global TriggerListeners registered with the Scheduler.

Throws:

SchedulerException

getTriggerListener

public TriggerListener getTriggerListener(java.lang.String name)
                                   throws SchedulerException

Get the non-global TriggerListener that has the given name.

Throws:

SchedulerException

addSchedulerListener

public void addSchedulerListener(SchedulerListener schedulerListener)
                          throws SchedulerException

Register the given SchedulerListener with the Scheduler.

Throws:

SchedulerException

removeSchedulerListener

public boolean removeSchedulerListener(SchedulerListener schedulerListener)
                                throws SchedulerException

Remove the given SchedulerListener from the Scheduler.

Returns:

true if the identifed listener was found in the list, and removed.

Throws:

SchedulerException

getSchedulerListeners

public java.util.List getSchedulerListeners()
                                     throws SchedulerException

Get a List containing all of the SchedulerListeners registered with the Scheduler.

Throws:

SchedulerException