org.quartz.Scheduler Maven / Gradle / Ivy
/*
* Copyright 2004-2005 OpenSymphony
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy
* of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
*/
/*
* Previously Copyright (c) 2001-2004 James House
*/
package org.quartz;
import java.util.Date;
import java.util.List;
import java.util.Set;
import org.quartz.spi.JobFactory;
/**
*
* This is the main interface of a Quartz Scheduler.
*
*
*
* A Scheduler maintains a registery of {@link org.quartz.JobDetail}
* s and {@link Trigger}s. Once registered, the Scheduler
* is responible for executing Job s when their associated
* Trigger s fire (when their scheduled time arrives).
*
*
*
* Scheduler instances are produced by a {@link 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 {@link org.quartz.Job}
* interface. {@link 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
* {@link 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 {@link JobListener} interface
* provides notifications of Job executions. The {@link TriggerListener}
* interface provides notifications of Trigger firings. The
* {@link 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.
*
*
* @see Job
* @see JobDetail
* @see Trigger
* @see JobListener
* @see TriggerListener
* @see SchedulerListener
*
* @author James House
* @author Sharada Jambula
*/
public interface Scheduler {
/*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Constants.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/**
*
* A (possibly) usefull constant that can be used for specifying the group
* that Job and Trigger instances belong to.
*
*/
public static final String DEFAULT_GROUP = "DEFAULT";
/**
*
* 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.
*
*/
public static final String DEFAULT_MANUAL_TRIGGERS = "MANUAL_TRIGGER";
/**
*
* 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.
*
*/
public static final String DEFAULT_RECOVERY_GROUP = "RECOVERING_JOBS";
/**
*
* 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.
*
*/
public static final String DEFAULT_FAIL_OVER_GROUP = "FAILED_OVER_JOBS";
/*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Interface.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/**
*
* Returns the name of the Scheduler.
*
*/
public String getSchedulerName() throws SchedulerException;
/**
*
* Returns the instance Id of the Scheduler.
*
*/
public String getSchedulerInstanceId() throws SchedulerException;
/**
*
* Returns the SchedulerContext of the Scheduler.
*
*/
public SchedulerContext getContext() throws SchedulerException;
///////////////////////////////////////////////////////////////////////////
///
/// Schedululer State Management Methods
///
///////////////////////////////////////////////////////////////////////////
/**
*
* Starts the Scheduler's threads that fire {@link Trigger}s.
* 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.
*
* @see #standby
* @see #shutdown
*/
public void start() throws SchedulerException;
/**
*
* Temporarily halts the Scheduler's firing of {@link Trigger}s.
*
*
*
* 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.
*
*
* @see #start()
* @see #pauseAll()
*/
public void standby() throws SchedulerException;
/**
* @deprecated replaced by better-named standby() method.
* @see #standby()
*/
public void pause() throws SchedulerException;
/**
*
* Reports whether the Scheduler is in stand-by mode.
*
*
* @see #standby()
* @see #start()
*/
public boolean isInStandbyMode() throws SchedulerException;
/**
* @deprecated
* @see #isInStandbyMode()
*/
public boolean isPaused() throws SchedulerException;
/**
*
* Halts the Scheduler's firing of {@link Trigger}s,
* and cleans up all resources associated with the Scheduler. Equivalent to
* shutdown(false).
*
*
*
* The scheduler cannot be re-started.
*
*
* @see #shutdown(boolean)
*/
public void shutdown() throws SchedulerException;
/**
*
* Halts the Scheduler's firing of {@link Trigger}s,
* and cleans up all resources associated with the Scheduler.
*
*
*
* The scheduler cannot be re-started.
*
*
* @param waitForJobsToComplete
* if true the scheduler will not allow this method
* to return until all currently executing jobs have completed.
*
* @see #shutdown
*/
public void shutdown(boolean waitForJobsToComplete)
throws SchedulerException;
/**
*
* Reports whether the Scheduler has been shutdown.
*
*/
public boolean isShutdown() 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.
*
*/
public SchedulerMetaData getMetaData() 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.
*
*
* @see JobExecutionContext
*/
public List getCurrentlyExecutingJobs() 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 opertunity for dependency injection.
*
*
* @see org.quart.spi.JobFactory
* @throws SchedulerException
*/
public void setJobFactory(JobFactory factory) throws SchedulerException;
///////////////////////////////////////////////////////////////////////////
///
/// Scheduling-related Methods
///
///////////////////////////////////////////////////////////////////////////
/**
*
* Add the given {@link org.quartz.JobDetail} to the
* Scheduler, and associate the given {@link 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.
*/
public Date scheduleJob(JobDetail jobDetail, Trigger trigger)
throws SchedulerException;
/**
*
* Schedule the given {@link org.quartz.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.
*/
public Date scheduleJob(Trigger trigger) throws SchedulerException;
/**
*
* Remove the indicated {@link Trigger} from the scheduler.
*
*/
public boolean unscheduleJob(String triggerName, String groupName)
throws SchedulerException;
/**
*
* Remove (delete) the {@link org.quartz.Trigger} with the
* given name, and store the new given one - which must be associated
* with the same job (the new trigger must have the job name & group specified)
* - however, the new trigger need not have the same name as the old trigger.
*
*
* @param triggerName
* The name of the Trigger to be replaced.
* @param groupName
* The group name of the Trigger to be replaced.
* @param newTrigger
* The new Trigger to be stored.
* @return 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.
*/
public Date rescheduleJob(String triggerName,
String groupName, Trigger newTrigger) 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.
*/
public void addJob(JobDetail jobDetail, boolean replace)
throws SchedulerException;
/**
*
* Delete the identified Job from the Scheduler - and any
* associated Triggers.
*
*
* @return true if the Job was found and deleted.
* @throws SchedulerException
* if there is an internal Scheduler error.
*/
public boolean deleteJob(String jobName, String groupName)
throws SchedulerException;
/**
*
* Trigger the identified {@link org.quartz.JobDetail}
* (execute it now) - the generated trigger will be non-volatile.
*
*/
public void triggerJob(String jobName, String groupName)
throws SchedulerException;
/**
*
* Trigger the identified {@link org.quartz.JobDetail}
* (execute it now) - the generated trigger will be volatile.
*
*/
public void triggerJobWithVolatileTrigger(String jobName, String groupName)
throws SchedulerException;
/**
*
* Trigger the identified {@link org.quartz.JobDetail}
* (execute it now) - the generated trigger will be non-volatile.
*
*
* @param jobName the name of the Job to trigger
* @param groupName the group name of the Job to trigger
* @param data the (possibly null) JobDataMap to be
* associated with the trigger that fires the job immediately.
*/
public void triggerJob(String jobName, String groupName, JobDataMap data)
throws SchedulerException;
/**
*
* Trigger the identified {@link org.quartz.JobDetail}
* (execute it now) - the generated trigger will be volatile.
*
*
* @param jobName the name of the Job to trigger
* @param groupName the group name of the Job to trigger
* @param data the (possibly null) JobDataMap to be
* associated with the trigger that fires the job immediately.
*/
public void triggerJobWithVolatileTrigger(String jobName, String groupName, JobDataMap data)
throws SchedulerException;
/**
*
* Pause the {@link org.quartz.JobDetail} with the given
* name - by pausing all of its current Triggers.
*
*
* @see #resumeJob(String, String)
*/
public void pauseJob(String jobName, String groupName)
throws SchedulerException;
/**
*
* Pause all of the {@link org.quartz.JobDetail}s 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.
*
*
* @see #resumeJobGroup(String)
*/
public void pauseJobGroup(String groupName) throws SchedulerException;
/**
*
* Pause the {@link Trigger} with the given name.
*
*
* @see #resumeTrigger(String, String)
*/
public void pauseTrigger(String triggerName, String groupName)
throws SchedulerException;
/**
*
* Pause all of the {@link Trigger}s 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.
*
*
* @see #resumeTriggerGroup(String)
*/
public void pauseTriggerGroup(String groupName) throws SchedulerException;
/**
*
* Resume (un-pause) the {@link org.quartz.JobDetail} with
* the given name.
*
*
*
* If any of the Job'sTrigger s missed one
* or more fire-times, then the Trigger's misfire
* instruction will be applied.
*
*
* @see #pauseJob(String, String)
*/
public void resumeJob(String jobName, String groupName)
throws SchedulerException;
/**
*
* Resume (un-pause) all of the {@link org.quartz.JobDetail}s
* in the given group.
*
*
*
* If any of the Job s had Trigger s that
* missed one or more fire-times, then the Trigger's
* misfire instruction will be applied.
*
*
* @see #pauseJobGroup(String)
*/
public void resumeJobGroup(String groupName) throws SchedulerException;
/**
*
* Resume (un-pause) the {@link Trigger} with the given
* name.
*
*
*
* If the Trigger missed one or more fire-times, then the
* Trigger's misfire instruction will be applied.
*
*
* @see #pauseTrigger(String, String)
*/
public void resumeTrigger(String triggerName, String groupName)
throws SchedulerException;
/**
*
* Resume (un-pause) all of the {@link Trigger}s in the
* given group.
*
*
*
* If any Trigger missed one or more fire-times, then the
* Trigger's misfire instruction will be applied.
*
*
* @see #pauseTriggerGroup(String)
*/
public void resumeTriggerGroup(String groupName) throws SchedulerException;
/**
*
* Pause all triggers - similar to calling pauseTriggerGroup(group)
* on every group, however, after using this method resumeAll()
* must be called to clear the scheduler's state of 'remembering' that all
* new triggers will be paused as they are added.
*
*
*
* When resumeAll() is called (to un-pause), trigger misfire
* instructions WILL be applied.
*
*
* @see #resumeAll()
* @see #pauseTriggerGroup(String)
* @see #standby()
*/
public void pauseAll() throws SchedulerException;
/**
*
* Resume (un-pause) all triggers - similar to calling
* resumeTriggerGroup(group) on every group.
*
*
*
* If any Trigger missed one or more fire-times, then the
* Trigger's misfire instruction will be applied.
*
*
* @see #pauseAll()
*/
public void resumeAll() throws SchedulerException;
/**
*
* Get the names of all known {@link org.quartz.JobDetail}
* groups.
*
*/
public String[] getJobGroupNames() throws SchedulerException;
/**
*
* Get the names of all the {@link org.quartz.JobDetail}s
* in the given group.
*
*/
public String[] getJobNames(String groupName) throws SchedulerException;
/**
*
* Get all {@link Trigger} s that are associated with the
* identified {@link org.quartz.JobDetail}.
*
*/
public Trigger[] getTriggersOfJob(String jobName, String groupName)
throws SchedulerException;
/**
*
* Get the names of all known {@link Trigger} groups.
*
*/
public String[] getTriggerGroupNames() throws SchedulerException;
/**
*
* Get the names of all the {@link Trigger}s in the given
* group.
*
*/
public String[] getTriggerNames(String groupName) throws SchedulerException;
/**
*
* Get the names of all {@link Trigger} groups that are paused.
*
*
* @return
* @throws SchedulerException
*/
public Set getPausedTriggerGroups() throws SchedulerException;
/**
*
* Get the {@link JobDetail} for the Job
* instance with the given name and group.
*
*/
public JobDetail getJobDetail(String jobName, String jobGroup)
throws SchedulerException;
/**
*
* Get the {@link Trigger} instance with the given name and
* group.
*
*/
public Trigger getTrigger(String triggerName, String triggerGroup)
throws SchedulerException;
/**
*
* Get the current state of the identified {@link Trigger}.
*
*
* @see Trigger#STATE_NORMAL
* @see Trigger#STATE_PAUSED
* @see Trigger#STATE_COMPLETE
* @see Trigger#STATE_ERROR
* @see Trigger#STATE_BLOCKED
* @see Trigger#STATE_NONE
*/
public int getTriggerState(String triggerName, String triggerGroup)
throws SchedulerException;
/**
*
* Add (register) the given Calendar to the Scheduler.
*
*
* @param updateTriggers whether or not to update existing triggers that
* referenced the already existing calendar so that they are 'correct'
* based on the new trigger.
*
*
* @throws SchedulerException
* if there is an internal Scheduler error, or a Calendar with
* the same name already exists, and replace is
* false.
*/
public void addCalendar(String calName, Calendar calendar, boolean replace, boolean updateTriggers)
throws SchedulerException;
/**
*
* Delete the identified Calendar from the Scheduler.
*
*
* @return true if the Calendar was found and deleted.
* @throws SchedulerException
* if there is an internal Scheduler error.
*/
public boolean deleteCalendar(String calName) throws SchedulerException;
/**
*
* Get the {@link Calendar} instance with the given name.
*
*/
public Calendar getCalendar(String calName) throws SchedulerException;
/**
*
* Get the names of all registered {@link Calendar}s.
*
*/
public String[] getCalendarNames() throws SchedulerException;
/**
*
* Request the interruption of all currently executing instances of the
* identified Job, which must be an implementor of the
* InterruptableJob interface.
*
*
*
* If more than one instance of the identified job is currently executing,
* the InterruptableJob#interrupt() method will be called on
* each instance. However, there is a limitation that in the case that
* interrupt() on one instances throws an exception, all
* remaining instances (that have not yet been interrupted) will not have
* their interrupt() method called.
*
*
*
* If you wish to interrupt a specific instance of a job (when more than
* one is executing) you can do so by calling
* {@link #getCurrentlyExecutingJobs()} to obtain a handle
* to the job instance, and then invoke interrupt() on it
* yourself.
*
*
* @param jobName
* @param groupName
* @return true is at least one instance of the identified job was found
* and interrupted.
* @throws UnableToInterruptJobException if the job does not implement
* InterruptableJob, or there is an exception while
* interrupting the job.
* @see InterruptableJob#interrupt()
* @see #getCurrentlyExecutingJobs()
*/
public boolean interrupt(String jobName, String groupName) throws UnableToInterruptJobException;
///////////////////////////////////////////////////////////////////////////
///
/// Listener-related Methods
///
///////////////////////////////////////////////////////////////////////////
/**
*
* Add the given {@link JobListener} to the Scheduler's
* global list.
*
*
*
* Listeners in the 'global' list receive notification of execution events
* for ALL {@link org.quartz.JobDetail}s.
*
*/
public void addGlobalJobListener(JobListener jobListener)
throws SchedulerException;
/**
*
* Add the given {@link JobListener} to the Scheduler's
* list, of registered JobListeners.
*/
public void addJobListener(JobListener jobListener)
throws SchedulerException;
/**
*
* Remove the given {@link JobListener} from the Scheduler's
* list of global listeners.
*
*
* @return true if the identifed listener was found in the list, and
* removed.
*/
public boolean removeGlobalJobListener(JobListener jobListener)
throws SchedulerException;
/**
*
* Remove the identifed {@link JobListener} from the Scheduler's
* list of registered listeners.
*
*
* @return true if the identifed listener was found in the list, and
* removed.
*/
public boolean removeJobListener(String name) throws SchedulerException;
/**
*
* Get a List containing all of the {@link JobListener} s in
* the Scheduler'sglobal list.
*
*/
public List getGlobalJobListeners() throws SchedulerException;
/**
*
* Get a Set containing the names of all the non-global{@link JobListener}
* s registered with the Scheduler.
*
*/
public Set getJobListenerNames() throws SchedulerException;
/**
*
* Get the non-global{@link JobListener} that has
* the given name.
*
*/
public JobListener getJobListener(String name) throws SchedulerException;
/**
*
* Add the given {@link TriggerListener} to the Scheduler's
* global list.
*
*
*
* Listeners in the 'global' list receive notification of execution events
* for ALL {@link Trigger}s.
*
*/
public void addGlobalTriggerListener(TriggerListener triggerListener)
throws SchedulerException;
/**
*
* Add the given {@link TriggerListener} to the Scheduler's
* list, of registered TriggerListeners.
*/
public void addTriggerListener(TriggerListener triggerListener)
throws SchedulerException;
/**
*
* Remove the given {@link TriggerListener} from the Scheduler's
* list of global listeners.
*
*
* @return true if the identifed listener was found in the list, and
* removed.
*/
public boolean removeGlobalTriggerListener(TriggerListener triggerListener)
throws SchedulerException;
/**
*
* Remove the identifed {@link TriggerListener} from the
* Scheduler's list of registered listeners.
*
*
* @return true if the identifed listener was found in the list, and
* removed.
*/
public boolean removeTriggerListener(String name) throws SchedulerException;
/**
*
* Get a List containing all of the {@link TriggerListener}
* s in the Scheduler'sglobal list.
*
*/
public List getGlobalTriggerListeners() throws SchedulerException;
/**
*
* Get a Set containing the names of all the non-global{@link TriggerListener}
* s registered with the Scheduler.
*
*/
public Set getTriggerListenerNames() throws SchedulerException;
/**
*
* Get the non-global{@link TriggerListener} that
* has the given name.
*
*/
public TriggerListener getTriggerListener(String name)
throws SchedulerException;
/**
*
* Register the given {@link SchedulerListener} with the
* Scheduler.
*
*/
public void addSchedulerListener(SchedulerListener schedulerListener)
throws SchedulerException;
/**
*
* Remove the given {@link SchedulerListener} from the
* Scheduler.
*
*
* @return true if the identifed listener was found in the list, and
* removed.
*/
public boolean removeSchedulerListener(SchedulerListener schedulerListener)
throws SchedulerException;
/**
*
* Get a List containing all of the {@link SchedulerListener}
* s registered with the Scheduler.
*
*/
public List getSchedulerListeners() throws SchedulerException;
}