com.helger.quartz.IScheduler Maven / Gradle / Ivy
/**
* All content copyright Terracotta, Inc., unless otherwise indicated. All rights reserved.
*
* Copyright (C) 2016-2020 Philip Helger (www.helger.com)
* philip[at]helger[dot]com
*
* 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 com.helger.quartz;
import java.io.Serializable;
import java.util.Date;
import java.util.List;
import java.util.Map;
import java.util.Set;
import com.helger.commons.collection.impl.ICommonsList;
import com.helger.commons.collection.impl.ICommonsSet;
import com.helger.quartz.ITrigger.ETriggerState;
import com.helger.quartz.impl.matchers.GroupMatcher;
import com.helger.quartz.spi.IJobFactory;
import com.helger.quartz.utils.Key;
/**
* This is the main interface of a Quartz Scheduler.
*
* A Scheduler maintains a registry of
* {@link com.helger.quartz.IJobDetail}s and
* {@link ITrigger}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 ISchedulerFactory}. 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 com.helger.quartz.IJob}
* interface. {@link IJobDetail} 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 IScheduler}. 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 IJobListener} interface
* provides notifications of Job executions. The
* {@link ITriggerListener} interface provides notifications of
* Trigger firings. The {@link ISchedulerListener}
* interface provides notifications of Scheduler events and errors.
* Listeners can be associated with local schedulers through the
* {@link IListenerManager} interface.
*
*
* The setup/configuration of a Scheduler instance is very
* customizable. Please consult the documentation distributed with Quartz.
*
*
* @see IJob
* @see IJobDetail
* @see JobBuilder
* @see ITrigger
* @see TriggerBuilder
* @see IJobListener
* @see ITriggerListener
* @see ISchedulerListener
* @author James House
* @author Sharada Jambula
*/
public interface IScheduler extends Serializable
{
/**
* 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 com.helger.quartz.IJobDetail#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 com.helger.quartz.IJobDetail#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 com.helger.quartz.IJobDetail#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 com.helger.quartz.IJobDetail#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 com.helger.quartz.IJobDetail#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 com.helger.quartz.IJobDetail#requestsRecovery()
*/
String FAILED_JOB_ORIGINAL_TRIGGER_SCHEDULED_FIRETIME_IN_MILLISECONDS = "QRTZ_FAILED_JOB_ORIG_TRIGGER_SCHEDULED_FIRETIME_IN_MILLISECONDS_AS_STRING";
/**
* 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 ITrigger}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 ITrigger}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 ITrigger}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 ITrigger}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 IJobExecutionContext
*/
ICommonsList 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 com.helger.quartz.spi.IJobFactory
*/
void setJobFactory (IJobFactory 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 IListenerManager
* @see IJobListener
* @see ITriggerListener
* @see ISchedulerListener
*/
IListenerManager getListenerManager () throws SchedulerException;
///////////////////////////////////////////////////////////////////////////
///
/// Scheduling-related Methods
///
///////////////////////////////////////////////////////////////////////////
/**
* Add the given {@link com.helger.quartz.IJobDetail} to the
* Scheduler, and associate the given {@link ITrigger} 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 (IJobDetail jobDetail, ITrigger trigger) throws SchedulerException;
/**
* Schedule the given {@link com.helger.quartz.ITrigger} 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 (ITrigger 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 (IJobDetail jobDetail,
Set triggersForJob,
boolean replace) throws SchedulerException;
/**
* Remove the indicated {@link ITrigger} 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 ITrigger}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 com.helger.quartz.ITrigger} 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 {@link ITrigger} 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, ITrigger 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(IJobDetail, 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 (IJobDetail 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 (IJobDetail 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 com.helger.quartz.IJobDetail}
* (execute it now).
*/
void triggerJob (JobKey jobKey) throws SchedulerException;
/**
* Trigger the identified {@link com.helger.quartz.IJobDetail}
* (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 com.helger.quartz.IJobDetail} 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 com.helger.quartz.IJobDetail}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(com.helger.quartz.impl.matchers.GroupMatcher)
*/
void pauseJobs (GroupMatcher matcher) throws SchedulerException;
/**
* Pause the {@link ITrigger} with the given key.
*
* @see #resumeTrigger(TriggerKey)
*/
void pauseTrigger (TriggerKey triggerKey) throws SchedulerException;
/**
* Pause all of the {@link ITrigger}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(com.helger.quartz.impl.matchers.GroupMatcher)
*/
void pauseTriggers (GroupMatcher matcher) throws SchedulerException;
/**
* Resume (un-pause) the {@link com.helger.quartz.IJobDetail}
* 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 com.helger.quartz.IJobDetail}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 ITrigger} 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 ITrigger}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(com.helger.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(com.helger.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 com.helger.quartz.IJobDetail} groups.
*/
ICommonsList getJobGroupNames () throws SchedulerException;
/**
* Get the keys of all the {@link com.helger.quartz.IJobDetail}s
* in the matching groups.
*
* @param matcher
* Matcher to evaluate against known groups
* @return Set of all keys matching
* @throws SchedulerException
* On error
*/
ICommonsSet getJobKeys (GroupMatcher matcher) throws SchedulerException;
/**
* Get all {@link ITrigger} s that are associated with the
* identified {@link com.helger.quartz.IJobDetail}.
*
* 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, ITrigger)}).
*
*/
ICommonsList getTriggersOfJob (JobKey jobKey) throws SchedulerException;
/**
* Get the names of all known {@link ITrigger} groups.
*/
ICommonsList getTriggerGroupNames () throws SchedulerException;
/**
* Get the names of all the {@link ITrigger}s in the given group.
*
* @param matcher
* Matcher to evaluate against known groups
* @return List of all keys matching
* @throws SchedulerException
* On error
*/
ICommonsSet getTriggerKeys (GroupMatcher matcher) throws SchedulerException;
/**
* Get the names of all {@link ITrigger} groups that are paused.
*/
ICommonsSet getPausedTriggerGroups () throws SchedulerException;
/**
* Get the {@link IJobDetail} 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(IJobDetail, boolean)}).
*
*/
IJobDetail getJobDetail (JobKey jobKey) throws SchedulerException;
/**
* Get the {@link ITrigger} 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, ITrigger)}).
*
*/
ITrigger getTrigger (TriggerKey triggerKey) throws SchedulerException;
/**
* Get the current state of the identified {@link ITrigger}.
*
* @see ITrigger.ETriggerState
*/
ETriggerState 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,
ICalendar 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 ICalendar} instance with the given name.
*/
ICalendar getCalendar (String calName) throws SchedulerException;
/**
* Get the names of all registered {@link ICalendar}s.
*/
ICommonsList 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 IInterruptableJob#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 IJobExecutionContext#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 IInterruptableJob#interrupt()
* @see #getCurrentlyExecutingJobs()
* @see IJobExecutionContext#getFireInstanceId()
* @see #interrupt(JobKey)
*/
boolean interrupt (String fireInstanceId) throws UnableToInterruptJobException;
/**
* Determine whether a {@link IJob} 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 ITrigger} 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 IJob}s,
* {@link ITrigger}s {@link ICalendar}s.
*
* @throws SchedulerException
*/
void clear () throws SchedulerException;
}