org.quartz.Scheduler Maven / Gradle / Ivy
Show all versions of quartz Show documentation
/*
* Copyright 2001-2009 Terracotta, Inc.
*
* 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.
*
*/
package org.quartz;
import java.util.Date;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.quartz.Trigger.TriggerState;
import org.quartz.impl.matchers.GroupMatcher;
import org.quartz.spi.JobFactory;
import org.quartz.utils.Key;
/**
* This is the main interface of a Quartz Scheduler.
*
*
* A Scheduler maintains a registry of {@link org.quartz.JobDetail}s
* and {@link Trigger}s. 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 {@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. Listeners can be associated with
* local schedulers through the {@link ListenerManager} interface.
*
*
*
* The setup/configuration of a Scheduler instance is very
* customizable. Please consult the documentation distributed with Quartz.
*
*
* @see Job
* @see JobDetail
* @see JobBuilder
* @see Trigger
* @see TriggerBuilder
* @see JobListener
* @see TriggerListener
* @see SchedulerListener
*
* @author James House
* @author Sharada Jambula
*/
public interface Scheduler {
/*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Constants.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/**
* A (possibly) useful constant that can be used for specifying the group
* that Job and Trigger instances belong to.
*/
String DEFAULT_GROUP = Key.DEFAULT_GROUP;
/**
* A constant Trigger group name used internally by the
* scheduler - clients should not use the value of this constant
* ("RECOVERING_JOBS") for the name of a Trigger's group.
*
* @see org.quartz.JobDetail#requestsRecovery()
*/
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 the name of a Trigger's group.
*
* @see org.quartz.JobDetail#requestsRecovery()
*/
String DEFAULT_FAIL_OVER_GROUP = "FAILED_OVER_JOBS";
/**
* A constant JobDataMap key that can be used to retrieve the
* name of the original Trigger from a recovery trigger's
* data map in the case of a job recovering after a failed scheduler
* instance.
*
* @see org.quartz.JobDetail#requestsRecovery()
*/
String FAILED_JOB_ORIGINAL_TRIGGER_NAME = "QRTZ_FAILED_JOB_ORIG_TRIGGER_NAME";
/**
* A constant JobDataMap key that can be used to retrieve the
* group of the original Trigger from a recovery trigger's
* data map in the case of a job recovering after a failed scheduler
* instance.
*
* @see org.quartz.JobDetail#requestsRecovery()
*/
String FAILED_JOB_ORIGINAL_TRIGGER_GROUP = "QRTZ_FAILED_JOB_ORIG_TRIGGER_GROUP";
/**
* A constant JobDataMap key that can be used to retrieve the
* fire time of the original Trigger from a recovery
* trigger's data map in the case of a job recovering after a failed scheduler
* instance.
*
* Note that this is the time the original firing actually occurred,
* which may be different from the scheduled fire time - as a trigger doesn't
* always fire exactly on time.
*
* @see org.quartz.JobDetail#requestsRecovery()
*/
String FAILED_JOB_ORIGINAL_TRIGGER_FIRETIME_IN_MILLISECONDS = "QRTZ_FAILED_JOB_ORIG_TRIGGER_FIRETIME_IN_MILLISECONDS_AS_STRING";
/**
* A constant JobDataMap key that can be used to retrieve the
* scheduled fire time of the original Trigger from a recovery
* trigger's data map in the case of a job recovering after a failed scheduler
* instance.
*
* Note that this is the time the original firing was scheduled for,
* which may be different from the actual firing time - as a trigger doesn't
* always fire exactly on time.
*
* @see org.quartz.JobDetail#requestsRecovery()
*/
String FAILED_JOB_ORIGINAL_TRIGGER_SCHEDULED_FIRETIME_IN_MILLISECONDS = "QRTZ_FAILED_JOB_ORIG_TRIGGER_SCHEDULED_FIRETIME_IN_MILLISECONDS_AS_STRING";
/*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Interface.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/**
* Returns the name of the Scheduler.
*/
String getSchedulerName() throws SchedulerException;
/**
* Returns the instance Id of the Scheduler.
*/
String getSchedulerInstanceId() throws SchedulerException;
/**
* Returns the SchedulerContext of the Scheduler.
*/
SchedulerContext getContext() throws SchedulerException;
///////////////////////////////////////////////////////////////////////////
///
/// Scheduler 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 #startDelayed(int)
* @see #standby()
* @see #shutdown()
*/
void start() 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.
*
* @see #start()
* @see #standby()
* @see #shutdown()
*/
void startDelayed(int seconds) throws SchedulerException;
/**
* Whether the scheduler has been started.
*
*
* Note: This only reflects whether {@link #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.
*
*
* @see #start()
* @see #isShutdown()
* @see #isInStandbyMode()
*/
boolean isStarted() 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()
*/
void standby() throws SchedulerException;
/**
* Reports whether the Scheduler is in stand-by mode.
*
* @see #standby()
* @see #start()
*/
boolean isInStandbyMode() 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)
*/
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
*/
void shutdown(boolean waitForJobsToComplete)
throws SchedulerException;
/**
* Reports whether the Scheduler has been shutdown.
*/
boolean isShutdown() throws SchedulerException;
/**
* Get a SchedulerMetaData object describing 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.
*
*/
SchedulerMetaData getMetaData() 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.
*
*
* @see JobExecutionContext
*/
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 opportunity for dependency injection.
*
*
* @see org.quartz.spi.JobFactory
*/
void setJobFactory(JobFactory factory) throws SchedulerException;
/**
* Get a reference to the scheduler's ListenerManager,
* through which listeners may be registered.
*
* @return the scheduler's ListenerManager
* @throws SchedulerException if the scheduler is not local
* @see ListenerManager
* @see JobListener
* @see TriggerListener
* @see SchedulerListener
*/
ListenerManager getListenerManager() 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.
*/
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.
*/
Date scheduleJob(Trigger trigger) throws SchedulerException;
/**
* Schedule all of the given jobs with the related set of triggers.
*
* If any of the given jobs or triggers already exist (or more
* specifically, if the keys are not unique) and the replace
* parameter is not set to true then an exception will be thrown.
*
* @throws ObjectAlreadyExistsException if the job/trigger keys
* are not unique and the replace flag is not set to true.
*/
void scheduleJobs(Map> triggersAndJobs, boolean replace) throws SchedulerException;
/**
* Schedule the given job with the related set of triggers.
*
* If any of the given job or triggers already exist (or more
* specifically, if the keys are not unique) and the replace
* parameter is not set to true then an exception will be thrown.
*
* @throws ObjectAlreadyExistsException if the job/trigger keys
* are not unique and the replace flag is not set to true.
*/
void scheduleJob(JobDetail jobDetail, Set triggersForJob, boolean replace) throws SchedulerException;
/**
* Remove the indicated {@link 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.
*/
boolean unscheduleJob(TriggerKey triggerKey)
throws SchedulerException;
/**
* Remove all of the indicated {@link Trigger}s 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.
*
* Note that while this bulk operation is likely more efficient than
* invoking unscheduleJob(TriggerKey triggerKey) several
* times, it may have the adverse affect of holding data locks for a
* single long duration of time (rather than lots of small durations
* of time).
*/
boolean unscheduleJobs(List triggerKeys)
throws SchedulerException;
/**
* Remove (delete) the {@link org.quartz.Trigger} 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 & group specified)
* - however, the new trigger need not have the same name as the old trigger.
*
* @param triggerKey identity of the trigger to replace
* @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 (and the
* new trigger is therefore not stored), otherwise
* the first fire time of the newly scheduled trigger is returned.
*/
Date rescheduleJob(TriggerKey triggerKey, 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.
*
*
* @see #addJob(JobDetail, boolean, boolean)
*
* @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.
*/
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.
*
*
* With the storeNonDurableWhileAwaitingScheduling parameter
* set to true, a non-durable job can be stored. Once it is
* scheduled, it will resume normal non-durable behavior (i.e. be deleted
* once there are no remaining associated triggers).
*
*
* @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.
*/
void addJob(JobDetail jobDetail, boolean replace, boolean storeNonDurableWhileAwaitingScheduling)
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.
*/
boolean deleteJob(JobKey jobKey)
throws SchedulerException;
/**
* Delete the identified Jobs from the Scheduler - and any
* associated Triggers.
*
* Note that while this bulk operation is likely more efficient than
* invoking deleteJob(JobKey jobKey) several
* times, it may have the adverse affect of holding data locks for a
* single long duration of time (rather than lots of small durations
* of time).
*
* @return true if all of the Jobs were found and deleted, false if
* one or more were not deleted.
* @throws SchedulerException
* if there is an internal Scheduler error.
*/
boolean deleteJobs(List jobKeys)
throws SchedulerException;
/**
* Trigger the identified {@link org.quartz.JobDetail}
* (execute it now).
*/
void triggerJob(JobKey jobKey)
throws SchedulerException;
/**
* Trigger the identified {@link org.quartz.JobDetail}
* (execute it now).
*
* @param data the (possibly null) JobDataMap to be
* associated with the trigger that fires the job immediately.
*/
void triggerJob(JobKey jobKey, JobDataMap data)
throws SchedulerException;
/**
* Pause the {@link org.quartz.JobDetail} with the given
* key - by pausing all of its current Triggers.
*
* @see #resumeJob(JobKey)
*/
void pauseJob(JobKey jobKey)
throws SchedulerException;
/**
* Pause all of the {@link org.quartz.JobDetail}s in the
* matching groups - by pausing all of their Triggers.
*
*
* The Scheduler will "remember" the groups paused, and impose the
* pause on any new jobs that are added to any of those groups
* until it is resumed.
*
*
* NOTE: There is a limitation that only exactly matched groups
* can be remembered as paused. For example, if there are pre-existing
* job in groups "aaa" and "bbb" and a matcher is given to pause
* groups that start with "a" then the group "aaa" will be remembered
* as paused and any subsequently added jobs in group "aaa" will be paused,
* however if a job is added to group "axx" it will not be paused,
* as "axx" wasn't known at the time the "group starts with a" matcher
* was applied. HOWEVER, if there are pre-existing groups "aaa" and
* "bbb" and a matcher is given to pause the group "axx" (with a
* group equals matcher) then no jobs will be paused, but it will be
* remembered that group "axx" is paused and later when a job is added
* in that group, it will become paused.
*
* @param matcher The matcher to evaluate against know groups
* @throws SchedulerException On error
* @see #resumeJobs(org.quartz.impl.matchers.GroupMatcher)
*/
void pauseJobs(GroupMatcher matcher) throws SchedulerException;
/**
* Pause the {@link Trigger} with the given key.
*
* @see #resumeTrigger(TriggerKey)
*/
void pauseTrigger(TriggerKey triggerKey)
throws SchedulerException;
/**
* Pause all of the {@link Trigger}s in the groups matching.
*
*
* The Scheduler will "remember" all the groups paused, and impose the
* pause on any new triggers that are added to any of those groups
* until it is resumed.
*
*
* NOTE: There is a limitation that only exactly matched groups
* can be remembered as paused. For example, if there are pre-existing
* triggers in groups "aaa" and "bbb" and a matcher is given to pause
* groups that start with "a" then the group "aaa" will be remembered as
* paused and any subsequently added triggers in that group be paused,
* however if a trigger is added to group "axx" it will not be paused,
* as "axx" wasn't known at the time the "group starts with a" matcher
* was applied. HOWEVER, if there are pre-existing groups "aaa" and
* "bbb" and a matcher is given to pause the group "axx" (with a
* group equals matcher) then no triggers will be paused, but it will be
* remembered that group "axx" is paused and later when a trigger is added
* in that group, it will become paused.
*
* @param matcher The matcher to evaluate against know groups
* @throws SchedulerException
* @see #resumeTriggers(org.quartz.impl.matchers.GroupMatcher)
*/
void pauseTriggers(GroupMatcher matcher) throws SchedulerException;
/**
* Resume (un-pause) the {@link org.quartz.JobDetail} with
* the given key.
*
*
* If any of the Job'sTrigger s missed one
* or more fire-times, then the Trigger's misfire
* instruction will be applied.
*
*
* @see #pauseJob(JobKey)
*/
void resumeJob(JobKey jobKey)
throws SchedulerException;
/**
* Resume (un-pause) all of the {@link org.quartz.JobDetail}s
* in matching groups.
*
*
* 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.
*
*
* @param matcher The matcher to evaluate against known paused groups
* @throws SchedulerException On error
* @see #pauseJobs(GroupMatcher)
*/
void resumeJobs(GroupMatcher matcher) throws SchedulerException;
/**
* Resume (un-pause) the {@link Trigger} with the given
* key.
*
*
* If the Trigger missed one or more fire-times, then the
* Trigger's misfire instruction will be applied.
*
*
* @see #pauseTrigger(TriggerKey)
*/
void resumeTrigger(TriggerKey triggerKey)
throws SchedulerException;
/**
* Resume (un-pause) all of the {@link Trigger}s in matching groups.
*
*
* If any Trigger missed one or more fire-times, then the
* Trigger's misfire instruction will be applied.
*
*
* @param matcher The matcher to evaluate against know paused groups
* @throws SchedulerException On error
* @see #pauseTriggers(org.quartz.impl.matchers.GroupMatcher)
*/
void resumeTriggers(GroupMatcher matcher) 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 #pauseTriggers(org.quartz.impl.matchers.GroupMatcher)
* @see #standby()
*/
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()
*/
void resumeAll() throws SchedulerException;
/**
* Get the names of all known {@link org.quartz.JobDetail}
* groups.
*/
List getJobGroupNames() throws SchedulerException;
/**
* Get the keys of all the {@link org.quartz.JobDetail}s
* in the matching groups.
* @param matcher Matcher to evaluate against known groups
* @return Set of all keys matching
* @throws SchedulerException On error
*/
Set getJobKeys(GroupMatcher matcher) throws SchedulerException;
/**
* Get all {@link Trigger} s that are associated with the
* identified {@link org.quartz.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 {@link #rescheduleJob(TriggerKey, Trigger)}).
*
*
*/
List getTriggersOfJob(JobKey jobKey)
throws SchedulerException;
/**
* Get the names of all known {@link Trigger} groups.
*/
List getTriggerGroupNames() throws SchedulerException;
/**
* Get the names of all the {@link Trigger}s in the given
* group.
* @param matcher Matcher to evaluate against known groups
* @return List of all keys matching
* @throws SchedulerException On error
*/
Set getTriggerKeys(GroupMatcher matcher) throws SchedulerException;
/**
* Get the names of all {@link Trigger} groups that are paused.
*/
Set getPausedTriggerGroups() throws SchedulerException;
/**
* Get the {@link 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 {@link #addJob(JobDetail, boolean)}).
*
*
*/
JobDetail getJobDetail(JobKey jobKey)
throws SchedulerException;
/**
* Get the {@link 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 {@link #rescheduleJob(TriggerKey, Trigger)}).
*
*/
Trigger getTrigger(TriggerKey triggerKey)
throws SchedulerException;
/**
* Get the current state of the identified {@link Trigger}.
*
* @see Trigger.TriggerState
*/
TriggerState getTriggerState(TriggerKey triggerKey)
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.
*/
void addCalendar(String calName, Calendar calendar, boolean replace, boolean updateTriggers)
throws SchedulerException;
/**
* Delete the identified Calendar from the Scheduler.
*
*
* If removal of the Calendar would result in
* Triggers pointing to non-existent calendars, then a
* SchedulerException will be thrown.
*
*
* @return true if the Calendar was found and deleted.
* @throws SchedulerException
* if there is an internal Scheduler error, or one or more
* triggers reference the calendar
*/
boolean deleteCalendar(String calName) throws SchedulerException;
/**
* Get the {@link Calendar} instance with the given name.
*/
Calendar getCalendar(String calName) throws SchedulerException;
/**
* Get the names of all registered {@link Calendar}s.
*/
List getCalendarNames() throws SchedulerException;
/**
* Request the interruption, within this Scheduler instance, 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.
*
*
*
* This method is not cluster aware. That is, it will only interrupt
* instances of the identified InterruptableJob currently executing in this
* Scheduler instance, not across the entire cluster.
*
*
* @return true if 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()
* @see #interrupt(String)
*/
boolean interrupt(JobKey jobKey) throws UnableToInterruptJobException;
/**
* Request the interruption, within this Scheduler instance, of the
* identified executing Job instance, which
* must be an implementor of the InterruptableJob interface.
*
*
* This method is not cluster aware. That is, it will only interrupt
* instances of the identified InterruptableJob currently executing in this
* Scheduler instance, not across the entire cluster.
*
*
* @param fireInstanceId the unique identifier of the job instance to
* be interrupted (see {@link JobExecutionContext#getFireInstanceId()}
* @return true if the identified job instance 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()
* @see JobExecutionContext#getFireInstanceId()
* @see #interrupt(JobKey)
*/
boolean interrupt(String fireInstanceId) throws UnableToInterruptJobException;
/**
* Determine whether a {@link Job} with the given identifier already
* exists within the scheduler.
*
* @param jobKey the identifier to check for
* @return true if a Job exists with the given identifier
* @throws SchedulerException
*/
boolean checkExists(JobKey jobKey) throws SchedulerException;
/**
* Determine whether a {@link Trigger} with the given identifier already
* exists within the scheduler.
*
* @param triggerKey the identifier to check for
* @return true if a Trigger exists with the given identifier
* @throws SchedulerException
*/
boolean checkExists(TriggerKey triggerKey) throws SchedulerException;
/**
* Clears (deletes!) all scheduling data - all {@link Job}s, {@link Trigger}s
* {@link Calendar}s.
*
* @throws SchedulerException
*/
void clear() throws SchedulerException;
}