0001: /*
0002: * Copyright 2004-2005 OpenSymphony
0003: *
0004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
0005: * use this file except in compliance with the License. You may obtain a copy
0006: * of the License at
0007: *
0008: * http://www.apache.org/licenses/LICENSE-2.0
0009: *
0010: * Unless required by applicable law or agreed to in writing, software
0011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
0012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
0013: * License for the specific language governing permissions and limitations
0014: * under the License.
0015: *
0016: */
0017:
0018: /*
0019: * Previously Copyright (c) 2001-2004 James House
0020: */
0021: package org.quartz;
0022:
0023: import java.util.Date;
0024: import java.util.List;
0025: import java.util.Set;
0026:
0027: import org.quartz.spi.JobFactory;
0028:
0029: /**
0030: * <p>
0031: * This is the main interface of a Quartz Scheduler.
0032: * </p>
0033: *
0034: * <p>
0035: * A <code>Scheduler</code> maintains a registery of <code>{@link org.quartz.JobDetail}</code>
0036: * s and <code>{@link Trigger}</code>s. Once registered, the <code>Scheduler</code>
0037: * is responible for executing <code>Job</code> s when their associated
0038: * <code>Trigger</code> s fire (when their scheduled time arrives).
0039: * </p>
0040: *
0041: * <p>
0042: * <code>Scheduler</code> instances are produced by a <code>{@link SchedulerFactory}</code>.
0043: * A scheduler that has already been created/initialized can be found and used
0044: * through the same factory that produced it. After a <code>Scheduler</code>
0045: * has been created, it is in "stand-by" mode, and must have its
0046: * <code>start()</code> method called before it will fire any <code>Job</code>s.
0047: * </p>
0048: *
0049: * <p>
0050: * <code>Job</code> s are to be created by the 'client program', by defining
0051: * a class that implements the <code>{@link org.quartz.Job}</code>
0052: * interface. <code>{@link JobDetail}</code> objects are then created (also
0053: * by the client) to define a individual instances of the <code>Job</code>.
0054: * <code>JobDetail</code> instances can then be registered with the <code>Scheduler</code>
0055: * via the <code>scheduleJob(JobDetail, Trigger)</code> or <code>addJob(JobDetail, boolean)</code>
0056: * method.
0057: * </p>
0058: *
0059: * <p>
0060: * <code>Trigger</code> s can then be defined to fire individual <code>Job</code>
0061: * instances based on given schedules. <code>SimpleTrigger</code> s are most
0062: * useful for one-time firings, or firing at an exact moment in time, with N
0063: * repeats with a given delay between them. <code>CronTrigger</code> s allow
0064: * scheduling based on time of day, day of week, day of month, and month of
0065: * year.
0066: * </p>
0067: *
0068: * <p>
0069: * <code>Job</code> s and <code>Trigger</code> s have a name and group
0070: * associated with them, which should uniquely identify them within a single
0071: * <code>{@link Scheduler}</code>. The 'group' feature may be useful for
0072: * creating logical groupings or categorizations of <code>Jobs</code> s and
0073: * <code>Triggers</code>s. If you don't have need for assigning a group to a
0074: * given <code>Jobs</code> of <code>Triggers</code>, then you can use the
0075: * <code>DEFAULT_GROUP</code> constant defined on this interface.
0076: * </p>
0077: *
0078: * <p>
0079: * Stored <code>Job</code> s can also be 'manually' triggered through the use
0080: * of the <code>triggerJob(String jobName, String jobGroup)</code> function.
0081: * </p>
0082: *
0083: * <p>
0084: * Client programs may also be interested in the 'listener' interfaces that are
0085: * available from Quartz. The <code>{@link JobListener}</code> interface
0086: * provides notifications of <code>Job</code> executions. The <code>{@link TriggerListener}</code>
0087: * interface provides notifications of <code>Trigger</code> firings. The
0088: * <code>{@link SchedulerListener}</code> interface provides notifications of
0089: * <code>Scheduler</code> events and errors.
0090: * </p>
0091: *
0092: * <p>
0093: * The setup/configuration of a <code>Scheduler</code> instance is very
0094: * customizable. Please consult the documentation distributed with Quartz.
0095: * </p>
0096: *
0097: * @see Job
0098: * @see JobDetail
0099: * @see Trigger
0100: * @see JobListener
0101: * @see TriggerListener
0102: * @see SchedulerListener
0103: *
0104: * @author James House
0105: * @author Sharada Jambula
0106: */
0107: public interface Scheduler {
0108:
0109: /*
0110: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0111: *
0112: * Constants.
0113: *
0114: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0115: */
0116:
0117: /**
0118: * <p>
0119: * A (possibly) usefull constant that can be used for specifying the group
0120: * that <code>Job</code> and <code>Trigger</code> instances belong to.
0121: * </p>
0122: */
0123: String DEFAULT_GROUP = "DEFAULT";
0124:
0125: /**
0126: * <p>
0127: * A constant <code>Trigger</code> group name used internally by the
0128: * scheduler - clients should not use the value of this constant
0129: * ("MANUAL_TRIGGER") for the name of a <code>Trigger</code>'s group.
0130: * </p>
0131: */
0132: String DEFAULT_MANUAL_TRIGGERS = "MANUAL_TRIGGER";
0133:
0134: /**
0135: * <p>
0136: * A constant <code>Trigger</code> group name used internally by the
0137: * scheduler - clients should not use the value of this constant
0138: * ("RECOVERING_JOBS") for the name of a <code>Trigger</code>'s group.
0139: * </p>
0140: *
0141: * @see org.quartz.JobDetail#requestsRecovery()
0142: */
0143: String DEFAULT_RECOVERY_GROUP = "RECOVERING_JOBS";
0144:
0145: /**
0146: * <p>
0147: * A constant <code>Trigger</code> group name used internally by the
0148: * scheduler - clients should not use the value of this constant
0149: * ("FAILED_OVER_JOBS") for the name of a <code>Trigger</code>'s group.
0150: * </p>
0151: *
0152: * @see org.quartz.JobDetail#requestsRecovery()
0153: */
0154: String DEFAULT_FAIL_OVER_GROUP = "FAILED_OVER_JOBS";
0155:
0156: /**
0157: * A constant <code>JobDataMap</code> key that can be used to retrieve the
0158: * name of the original <code>Trigger</code> from a recovery trigger's
0159: * data map in the case of a job recovering after a failed scheduler
0160: * instance.
0161: *
0162: * @see org.quartz.JobDetail#requestsRecovery()
0163: */
0164: String FAILED_JOB_ORIGINAL_TRIGGER_NAME = "QRTZ_FAILED_JOB_ORIG_TRIGGER_NAME";
0165:
0166: /**
0167: * A constant <code>JobDataMap</code> key that can be used to retrieve the
0168: * group of the original <code>Trigger</code> from a recovery trigger's
0169: * data map in the case of a job recovering after a failed scheduler
0170: * instance.
0171: *
0172: * @see org.quartz.JobDetail#requestsRecovery()
0173: */
0174: String FAILED_JOB_ORIGINAL_TRIGGER_GROUP = "QRTZ_FAILED_JOB_ORIG_TRIGGER_GROUP";
0175:
0176: /**
0177: * A constant <code>JobDataMap</code> key that can be used to retrieve the
0178: * scheduled fire time of the original <code>Trigger</code> from a recovery
0179: * trigger's data map in the case of a job recovering after a failed scheduler
0180: * instance.
0181: *
0182: * @see org.quartz.JobDetail#requestsRecovery()
0183: */
0184: String FAILED_JOB_ORIGINAL_TRIGGER_FIRETIME_IN_MILLISECONDS = "QRTZ_FAILED_JOB_ORIG_TRIGGER_FIRETIME_IN_MILLISECONDS_AS_STRING";
0185:
0186: /*
0187: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0188: *
0189: * Interface.
0190: *
0191: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0192: */
0193:
0194: /**
0195: * <p>
0196: * Returns the name of the <code>Scheduler</code>.
0197: * </p>
0198: */
0199: String getSchedulerName() throws SchedulerException;
0200:
0201: /**
0202: * <p>
0203: * Returns the instance Id of the <code>Scheduler</code>.
0204: * </p>
0205: */
0206: String getSchedulerInstanceId() throws SchedulerException;
0207:
0208: /**
0209: * <p>
0210: * Returns the <code>SchedulerContext</code> of the <code>Scheduler</code>.
0211: * </p>
0212: */
0213: SchedulerContext getContext() throws SchedulerException;
0214:
0215: ///////////////////////////////////////////////////////////////////////////
0216: ///
0217: /// Schedululer State Management Methods
0218: ///
0219: ///////////////////////////////////////////////////////////////////////////
0220:
0221: /**
0222: * <p>
0223: * Starts the <code>Scheduler</code>'s threads that fire <code>{@link Trigger}s</code>.
0224: * When a scheduler is first created it is in "stand-by" mode, and will not
0225: * fire triggers. The scheduler can also be put into stand-by mode by
0226: * calling the <code>standby()</code> method.
0227: * </p>
0228: *
0229: * <p>
0230: * The misfire/recovery process will be started, if it is the initial call
0231: * to this method on this scheduler instance.
0232: * </p>
0233: *
0234: * @throws SchedulerException
0235: * if <code>shutdown()</code> has been called, or there is an
0236: * error within the <code>Scheduler</code>.
0237: *
0238: * @see #standby
0239: * @see #shutdown
0240: */
0241: void start() throws SchedulerException;
0242:
0243: /**
0244: * Whether the scheduler has been started.
0245: *
0246: * <p>
0247: * Note: This only reflects whether <code>{@link #start()}</code> has ever
0248: * been called on this Scheduler, so it will return <code>true</code> even
0249: * if the <code>Scheduler</code> is currently in standby mode or has been
0250: * since shutdown.
0251: * </p>
0252: *
0253: * @see #start()
0254: * @see #isShutdown()
0255: * @see #isInStandbyMode()
0256: */
0257: boolean isStarted() throws SchedulerException;
0258:
0259: /**
0260: * <p>
0261: * Temporarily halts the <code>Scheduler</code>'s firing of <code>{@link Trigger}s</code>.
0262: * </p>
0263: *
0264: * <p>
0265: * When <code>start()</code> is called (to bring the scheduler out of
0266: * stand-by mode), trigger misfire instructions will NOT be applied
0267: * during the execution of the <code>start()</code> method - any misfires
0268: * will be detected immediately afterward (by the <code>JobStore</code>'s
0269: * normal process).
0270: * </p>
0271: *
0272: * <p>
0273: * The scheduler is not destroyed, and can be re-started at any time.
0274: * </p>
0275: *
0276: * @see #start()
0277: * @see #pauseAll()
0278: */
0279: void standby() throws SchedulerException;
0280:
0281: /**
0282: * @deprecated replaced by better-named standby() method.
0283: * @see #standby()
0284: */
0285: void pause() throws SchedulerException;
0286:
0287: /**
0288: * <p>
0289: * Reports whether the <code>Scheduler</code> is in stand-by mode.
0290: * </p>
0291: *
0292: * @see #standby()
0293: * @see #start()
0294: */
0295: boolean isInStandbyMode() throws SchedulerException;
0296:
0297: /**
0298: * @deprecated
0299: * @see #isInStandbyMode()
0300: */
0301: boolean isPaused() throws SchedulerException;
0302:
0303: /**
0304: * <p>
0305: * Halts the <code>Scheduler</code>'s firing of <code>{@link Trigger}s</code>,
0306: * and cleans up all resources associated with the Scheduler. Equivalent to
0307: * <code>shutdown(false)</code>.
0308: * </p>
0309: *
0310: * <p>
0311: * The scheduler cannot be re-started.
0312: * </p>
0313: *
0314: * @see #shutdown(boolean)
0315: */
0316: void shutdown() throws SchedulerException;
0317:
0318: /**
0319: * <p>
0320: * Halts the <code>Scheduler</code>'s firing of <code>{@link Trigger}s</code>,
0321: * and cleans up all resources associated with the Scheduler.
0322: * </p>
0323: *
0324: * <p>
0325: * The scheduler cannot be re-started.
0326: * </p>
0327: *
0328: * @param waitForJobsToComplete
0329: * if <code>true</code> the scheduler will not allow this method
0330: * to return until all currently executing jobs have completed.
0331: *
0332: * @see #shutdown
0333: */
0334: void shutdown(boolean waitForJobsToComplete)
0335: throws SchedulerException;
0336:
0337: /**
0338: * <p>
0339: * Reports whether the <code>Scheduler</code> has been shutdown.
0340: * </p>
0341: */
0342: boolean isShutdown() throws SchedulerException;
0343:
0344: /**
0345: * <p>
0346: * Get a <code>SchedulerMetaData</code> object describiing the settings
0347: * and capabilities of the scheduler instance.
0348: * </p>
0349: *
0350: * <p>
0351: * Note that the data returned is an 'instantaneous' snap-shot, and that as
0352: * soon as it's returned, the meta data values may be different.
0353: * </p>
0354: */
0355: SchedulerMetaData getMetaData() throws SchedulerException;
0356:
0357: /**
0358: * <p>
0359: * Return a list of <code>JobExecutionContext</code> objects that
0360: * represent all currently executing Jobs in this Scheduler instance.
0361: * </p>
0362: *
0363: * <p>
0364: * This method is not cluster aware. That is, it will only return Jobs
0365: * currently executing in this Scheduler instance, not across the entire
0366: * cluster.
0367: * </p>
0368: *
0369: * <p>
0370: * Note that the list returned is an 'instantaneous' snap-shot, and that as
0371: * soon as it's returned, the true list of executing jobs may be different.
0372: * Also please read the doc associated with <code>JobExecutionContext</code>-
0373: * especially if you're using RMI.
0374: * </p>
0375: *
0376: * @see JobExecutionContext
0377: */
0378: List getCurrentlyExecutingJobs() throws SchedulerException;
0379:
0380: /**
0381: * <p>
0382: * Set the <code>JobFactory</code> that will be responsible for producing
0383: * instances of <code>Job</code> classes.
0384: * </p>
0385: *
0386: * <p>
0387: * JobFactories may be of use to those wishing to have their application
0388: * produce <code>Job</code> instances via some special mechanism, such as to
0389: * give the opertunity for dependency injection.
0390: * </p>
0391: *
0392: * @see org.quartz.spi.JobFactory
0393: */
0394: void setJobFactory(JobFactory factory) throws SchedulerException;
0395:
0396: ///////////////////////////////////////////////////////////////////////////
0397: ///
0398: /// Scheduling-related Methods
0399: ///
0400: ///////////////////////////////////////////////////////////////////////////
0401:
0402: /**
0403: * <p>
0404: * Add the given <code>{@link org.quartz.JobDetail}</code> to the
0405: * Scheduler, and associate the given <code>{@link Trigger}</code> with
0406: * it.
0407: * </p>
0408: *
0409: * <p>
0410: * If the given Trigger does not reference any <code>Job</code>, then it
0411: * will be set to reference the Job passed with it into this method.
0412: * </p>
0413: *
0414: * @throws SchedulerException
0415: * if the Job or Trigger cannot be added to the Scheduler, or
0416: * there is an internal Scheduler error.
0417: */
0418: Date scheduleJob(JobDetail jobDetail, Trigger trigger)
0419: throws SchedulerException;
0420:
0421: /**
0422: * <p>
0423: * Schedule the given <code>{@link org.quartz.Trigger}</code> with the
0424: * <code>Job</code> identified by the <code>Trigger</code>'s settings.
0425: * </p>
0426: *
0427: * @throws SchedulerException
0428: * if the indicated Job does not exist, or the Trigger cannot be
0429: * added to the Scheduler, or there is an internal Scheduler
0430: * error.
0431: */
0432: Date scheduleJob(Trigger trigger) throws SchedulerException;
0433:
0434: /**
0435: * <p>
0436: * Remove the indicated <code>{@link Trigger}</code> from the scheduler.
0437: * </p>
0438: */
0439: boolean unscheduleJob(String triggerName, String groupName)
0440: throws SchedulerException;
0441:
0442: /**
0443: * <p>
0444: * Remove (delete) the <code>{@link org.quartz.Trigger}</code> with the
0445: * given name, and store the new given one - which must be associated
0446: * with the same job (the new trigger must have the job name & group specified)
0447: * - however, the new trigger need not have the same name as the old trigger.
0448: * </p>
0449: *
0450: * @param triggerName
0451: * The name of the <code>Trigger</code> to be replaced.
0452: * @param groupName
0453: * The group name of the <code>Trigger</code> to be replaced.
0454: * @param newTrigger
0455: * The new <code>Trigger</code> to be stored.
0456: * @return <code>null</code> if a <code>Trigger</code> with the given
0457: * name & group was not found and removed from the store, otherwise
0458: * the first fire time of the newly scheduled trigger.
0459: */
0460: Date rescheduleJob(String triggerName, String groupName,
0461: Trigger newTrigger) throws SchedulerException;
0462:
0463: /**
0464: * <p>
0465: * Add the given <code>Job</code> to the Scheduler - with no associated
0466: * <code>Trigger</code>. The <code>Job</code> will be 'dormant' until
0467: * it is scheduled with a <code>Trigger</code>, or <code>Scheduler.triggerJob()</code>
0468: * is called for it.
0469: * </p>
0470: *
0471: * <p>
0472: * The <code>Job</code> must by definition be 'durable', if it is not,
0473: * SchedulerException will be thrown.
0474: * </p>
0475: *
0476: * @throws SchedulerException
0477: * if there is an internal Scheduler error, or if the Job is not
0478: * durable, or a Job with the same name already exists, and
0479: * <code>replace</code> is <code>false</code>.
0480: */
0481: void addJob(JobDetail jobDetail, boolean replace)
0482: throws SchedulerException;
0483:
0484: /**
0485: * <p>
0486: * Delete the identified <code>Job</code> from the Scheduler - and any
0487: * associated <code>Trigger</code>s.
0488: * </p>
0489: *
0490: * @return true if the Job was found and deleted.
0491: * @throws SchedulerException
0492: * if there is an internal Scheduler error.
0493: */
0494: boolean deleteJob(String jobName, String groupName)
0495: throws SchedulerException;
0496:
0497: /**
0498: * <p>
0499: * Trigger the identified <code>{@link org.quartz.JobDetail}</code>
0500: * (execute it now) - the generated trigger will be non-volatile.
0501: * </p>
0502: */
0503: void triggerJob(String jobName, String groupName)
0504: throws SchedulerException;
0505:
0506: /**
0507: * <p>
0508: * Trigger the identified <code>{@link org.quartz.JobDetail}</code>
0509: * (execute it now) - the generated trigger will be volatile.
0510: * </p>
0511: */
0512: void triggerJobWithVolatileTrigger(String jobName, String groupName)
0513: throws SchedulerException;
0514:
0515: /**
0516: * <p>
0517: * Trigger the identified <code>{@link org.quartz.JobDetail}</code>
0518: * (execute it now) - the generated trigger will be non-volatile.
0519: * </p>
0520: *
0521: * @param jobName the name of the Job to trigger
0522: * @param groupName the group name of the Job to trigger
0523: * @param data the (possibly <code>null</code>) JobDataMap to be
0524: * associated with the trigger that fires the job immediately.
0525: */
0526: void triggerJob(String jobName, String groupName, JobDataMap data)
0527: throws SchedulerException;
0528:
0529: /**
0530: * <p>
0531: * Trigger the identified <code>{@link org.quartz.JobDetail}</code>
0532: * (execute it now) - the generated trigger will be volatile.
0533: * </p>
0534: *
0535: * @param jobName the name of the Job to trigger
0536: * @param groupName the group name of the Job to trigger
0537: * @param data the (possibly <code>null</code>) JobDataMap to be
0538: * associated with the trigger that fires the job immediately.
0539: */
0540: void triggerJobWithVolatileTrigger(String jobName,
0541: String groupName, JobDataMap data)
0542: throws SchedulerException;
0543:
0544: /**
0545: * <p>
0546: * Pause the <code>{@link org.quartz.JobDetail}</code> with the given
0547: * name - by pausing all of its current <code>Trigger</code>s.
0548: * </p>
0549: *
0550: * @see #resumeJob(String, String)
0551: */
0552: void pauseJob(String jobName, String groupName)
0553: throws SchedulerException;
0554:
0555: /**
0556: * <p>
0557: * Pause all of the <code>{@link org.quartz.JobDetail}s</code> in the
0558: * given group - by pausing all of their <code>Trigger</code>s.
0559: * </p>
0560: *
0561: * <p>
0562: * The Scheduler will "remember" that the group is paused, and impose the
0563: * pause on any new jobs that are added to the group while the group is
0564: * paused.
0565: * </p>
0566: *
0567: * @see #resumeJobGroup(String)
0568: */
0569: void pauseJobGroup(String groupName) throws SchedulerException;
0570:
0571: /**
0572: * <p>
0573: * Pause the <code>{@link Trigger}</code> with the given name.
0574: * </p>
0575: *
0576: * @see #resumeTrigger(String, String)
0577: */
0578: void pauseTrigger(String triggerName, String groupName)
0579: throws SchedulerException;
0580:
0581: /**
0582: * <p>
0583: * Pause all of the <code>{@link Trigger}s</code> in the given group.
0584: * </p>
0585: *
0586: * <p>
0587: * The Scheduler will "remember" that the group is paused, and impose the
0588: * pause on any new triggers that are added to the group while the group is
0589: * paused.
0590: * </p>
0591: *
0592: * @see #resumeTriggerGroup(String)
0593: */
0594: void pauseTriggerGroup(String groupName) throws SchedulerException;
0595:
0596: /**
0597: * <p>
0598: * Resume (un-pause) the <code>{@link org.quartz.JobDetail}</code> with
0599: * the given name.
0600: * </p>
0601: *
0602: * <p>
0603: * If any of the <code>Job</code>'s<code>Trigger</code> s missed one
0604: * or more fire-times, then the <code>Trigger</code>'s misfire
0605: * instruction will be applied.
0606: * </p>
0607: *
0608: * @see #pauseJob(String, String)
0609: */
0610: void resumeJob(String jobName, String groupName)
0611: throws SchedulerException;
0612:
0613: /**
0614: * <p>
0615: * Resume (un-pause) all of the <code>{@link org.quartz.JobDetail}s</code>
0616: * in the given group.
0617: * </p>
0618: *
0619: * <p>
0620: * If any of the <code>Job</code> s had <code>Trigger</code> s that
0621: * missed one or more fire-times, then the <code>Trigger</code>'s
0622: * misfire instruction will be applied.
0623: * </p>
0624: *
0625: * @see #pauseJobGroup(String)
0626: */
0627: void resumeJobGroup(String groupName) throws SchedulerException;
0628:
0629: /**
0630: * <p>
0631: * Resume (un-pause) the <code>{@link Trigger}</code> with the given
0632: * name.
0633: * </p>
0634: *
0635: * <p>
0636: * If the <code>Trigger</code> missed one or more fire-times, then the
0637: * <code>Trigger</code>'s misfire instruction will be applied.
0638: * </p>
0639: *
0640: * @see #pauseTrigger(String, String)
0641: */
0642: void resumeTrigger(String triggerName, String groupName)
0643: throws SchedulerException;
0644:
0645: /**
0646: * <p>
0647: * Resume (un-pause) all of the <code>{@link Trigger}s</code> in the
0648: * given group.
0649: * </p>
0650: *
0651: * <p>
0652: * If any <code>Trigger</code> missed one or more fire-times, then the
0653: * <code>Trigger</code>'s misfire instruction will be applied.
0654: * </p>
0655: *
0656: * @see #pauseTriggerGroup(String)
0657: */
0658: void resumeTriggerGroup(String groupName) throws SchedulerException;
0659:
0660: /**
0661: * <p>
0662: * Pause all triggers - similar to calling <code>pauseTriggerGroup(group)</code>
0663: * on every group, however, after using this method <code>resumeAll()</code>
0664: * must be called to clear the scheduler's state of 'remembering' that all
0665: * new triggers will be paused as they are added.
0666: * </p>
0667: *
0668: * <p>
0669: * When <code>resumeAll()</code> is called (to un-pause), trigger misfire
0670: * instructions WILL be applied.
0671: * </p>
0672: *
0673: * @see #resumeAll()
0674: * @see #pauseTriggerGroup(String)
0675: * @see #standby()
0676: */
0677: void pauseAll() throws SchedulerException;
0678:
0679: /**
0680: * <p>
0681: * Resume (un-pause) all triggers - similar to calling
0682: * <code>resumeTriggerGroup(group)</code> on every group.
0683: * </p>
0684: *
0685: * <p>
0686: * If any <code>Trigger</code> missed one or more fire-times, then the
0687: * <code>Trigger</code>'s misfire instruction will be applied.
0688: * </p>
0689: *
0690: * @see #pauseAll()
0691: */
0692: void resumeAll() throws SchedulerException;
0693:
0694: /**
0695: * <p>
0696: * Get the names of all known <code>{@link org.quartz.JobDetail}</code>
0697: * groups.
0698: * </p>
0699: */
0700: String[] getJobGroupNames() throws SchedulerException;
0701:
0702: /**
0703: * <p>
0704: * Get the names of all the <code>{@link org.quartz.JobDetail}s</code>
0705: * in the given group.
0706: * </p>
0707: */
0708: String[] getJobNames(String groupName) throws SchedulerException;
0709:
0710: /**
0711: * <p>
0712: * Get all <code>{@link Trigger}</code> s that are associated with the
0713: * identified <code>{@link org.quartz.JobDetail}</code>.
0714: * </p>
0715: */
0716: Trigger[] getTriggersOfJob(String jobName, String groupName)
0717: throws SchedulerException;
0718:
0719: /**
0720: * <p>
0721: * Get the names of all known <code>{@link Trigger}</code> groups.
0722: * </p>
0723: */
0724: String[] getTriggerGroupNames() throws SchedulerException;
0725:
0726: /**
0727: * <p>
0728: * Get the names of all the <code>{@link Trigger}s</code> in the given
0729: * group.
0730: * </p>
0731: */
0732: String[] getTriggerNames(String groupName)
0733: throws SchedulerException;
0734:
0735: /**
0736: * <p>
0737: * Get the names of all <code>{@link Trigger}</code> groups that are paused.
0738: * </p>
0739: */
0740: Set getPausedTriggerGroups() throws SchedulerException;
0741:
0742: /**
0743: * <p>
0744: * Get the <code>{@link JobDetail}</code> for the <code>Job</code>
0745: * instance with the given name and group.
0746: * </p>
0747: */
0748: JobDetail getJobDetail(String jobName, String jobGroup)
0749: throws SchedulerException;
0750:
0751: /**
0752: * <p>
0753: * Get the <code>{@link Trigger}</code> instance with the given name and
0754: * group.
0755: * </p>
0756: */
0757: Trigger getTrigger(String triggerName, String triggerGroup)
0758: throws SchedulerException;
0759:
0760: /**
0761: * <p>
0762: * Get the current state of the identified <code>{@link Trigger}</code>.
0763: * </p>
0764: *
0765: * @see Trigger#STATE_NORMAL
0766: * @see Trigger#STATE_PAUSED
0767: * @see Trigger#STATE_COMPLETE
0768: * @see Trigger#STATE_ERROR
0769: * @see Trigger#STATE_BLOCKED
0770: * @see Trigger#STATE_NONE
0771: */
0772: int getTriggerState(String triggerName, String triggerGroup)
0773: throws SchedulerException;
0774:
0775: /**
0776: * <p>
0777: * Add (register) the given <code>Calendar</code> to the Scheduler.
0778: * </p>
0779: *
0780: * @param updateTriggers whether or not to update existing triggers that
0781: * referenced the already existing calendar so that they are 'correct'
0782: * based on the new trigger.
0783: *
0784: *
0785: * @throws SchedulerException
0786: * if there is an internal Scheduler error, or a Calendar with
0787: * the same name already exists, and <code>replace</code> is
0788: * <code>false</code>.
0789: */
0790: void addCalendar(String calName, Calendar calendar,
0791: boolean replace, boolean updateTriggers)
0792: throws SchedulerException;
0793:
0794: /**
0795: * <p>
0796: * Delete the identified <code>Calendar</code> from the Scheduler.
0797: * </p>
0798: *
0799: * @return true if the Calendar was found and deleted.
0800: * @throws SchedulerException
0801: * if there is an internal Scheduler error.
0802: */
0803: boolean deleteCalendar(String calName) throws SchedulerException;
0804:
0805: /**
0806: * <p>
0807: * Get the <code>{@link Calendar}</code> instance with the given name.
0808: * </p>
0809: */
0810: Calendar getCalendar(String calName) throws SchedulerException;
0811:
0812: /**
0813: * <p>
0814: * Get the names of all registered <code>{@link Calendar}s</code>.
0815: * </p>
0816: */
0817: String[] getCalendarNames() throws SchedulerException;
0818:
0819: /**
0820: * <p>
0821: * Request the interruption, within this Scheduler instance, of all
0822: * currently executing instances of the identified <code>Job</code>, which
0823: * must be an implementor of the <code>InterruptableJob</code> interface.
0824: * </p>
0825: *
0826: * <p>
0827: * If more than one instance of the identified job is currently executing,
0828: * the <code>InterruptableJob#interrupt()</code> method will be called on
0829: * each instance. However, there is a limitation that in the case that
0830: * <code>interrupt()</code> on one instances throws an exception, all
0831: * remaining instances (that have not yet been interrupted) will not have
0832: * their <code>interrupt()</code> method called.
0833: * </p>
0834: *
0835: * <p>
0836: * If you wish to interrupt a specific instance of a job (when more than
0837: * one is executing) you can do so by calling
0838: * <code>{@link #getCurrentlyExecutingJobs()}</code> to obtain a handle
0839: * to the job instance, and then invoke <code>interrupt()</code> on it
0840: * yourself.
0841: * </p>
0842: *
0843: * <p>
0844: * This method is not cluster aware. That is, it will only interrupt
0845: * instances of the identified InterruptableJob currently executing in this
0846: * Scheduler instance, not across the entire cluster.
0847: * </p>
0848: *
0849: * @param jobName
0850: * @param groupName
0851: * @return true is at least one instance of the identified job was found
0852: * and interrupted.
0853: * @throws UnableToInterruptJobException if the job does not implement
0854: * <code>InterruptableJob</code>, or there is an exception while
0855: * interrupting the job.
0856: * @see InterruptableJob#interrupt()
0857: * @see #getCurrentlyExecutingJobs()
0858: */
0859: boolean interrupt(String jobName, String groupName)
0860: throws UnableToInterruptJobException;
0861:
0862: ///////////////////////////////////////////////////////////////////////////
0863: ///
0864: /// Listener-related Methods
0865: ///
0866: ///////////////////////////////////////////////////////////////////////////
0867:
0868: /**
0869: * <p>
0870: * Add the given <code>{@link JobListener}</code> to the <code>Scheduler</code>'s
0871: * <i>global</i> list.
0872: * </p>
0873: *
0874: * <p>
0875: * Listeners in the 'global' list receive notification of execution events
0876: * for ALL <code>{@link org.quartz.JobDetail}</code>s.
0877: * </p>
0878: */
0879: void addGlobalJobListener(JobListener jobListener)
0880: throws SchedulerException;
0881:
0882: /**
0883: * <p>
0884: * Add the given <code>{@link JobListener}</code> to the <code>Scheduler</code>'s
0885: * list, of registered <code>JobListener</code>s.
0886: */
0887: void addJobListener(JobListener jobListener)
0888: throws SchedulerException;
0889:
0890: /**
0891: * <p>
0892: * Remove the given <code>{@link JobListener}</code> from the <code>Scheduler</code>'s
0893: * list of <i>global</i> listeners.
0894: * </p>
0895: *
0896: * @return true if the identifed listener was found in the list, and
0897: * removed.
0898: *
0899: * @deprecated Use <code>{@link #removeGlobalJobListener(String)}</code>
0900: */
0901: boolean removeGlobalJobListener(JobListener jobListener)
0902: throws SchedulerException;
0903:
0904: /**
0905: * <p>
0906: * Remove the identifed <code>{@link JobListener}</code> from the <code>Scheduler</code>'s
0907: * list of <i>global</i> listeners.
0908: * </p>
0909: *
0910: * @return true if the identifed listener was found in the list, and
0911: * removed.
0912: */
0913: boolean removeGlobalJobListener(String name)
0914: throws SchedulerException;
0915:
0916: /**
0917: * <p>
0918: * Remove the identifed <code>{@link JobListener}</code> from the <code>Scheduler</code>'s
0919: * list of registered listeners.
0920: * </p>
0921: *
0922: * @return true if the identifed listener was found in the list, and
0923: * removed.
0924: */
0925: boolean removeJobListener(String name) throws SchedulerException;
0926:
0927: /**
0928: * <p>
0929: * Get a List containing all of the <code>{@link JobListener}</code> s in
0930: * the <code>Scheduler</code>'s<i>global</i> list.
0931: * </p>
0932: */
0933: List getGlobalJobListeners() throws SchedulerException;
0934:
0935: /**
0936: * <p>
0937: * Get a Set containing the names of all the <i>non-global</i><code>{@link JobListener}</code>
0938: * s registered with the <code>Scheduler</code>.
0939: * </p>
0940: */
0941: Set getJobListenerNames() throws SchedulerException;
0942:
0943: /**
0944: * <p>
0945: * Get the <i>global</i><code>{@link JobListener}</code> that has
0946: * the given name.
0947: * </p>
0948: */
0949: JobListener getGlobalJobListener(String name)
0950: throws SchedulerException;
0951:
0952: /**
0953: * <p>
0954: * Get the <i>non-global</i><code>{@link JobListener}</code> that has
0955: * the given name.
0956: * </p>
0957: */
0958: JobListener getJobListener(String name) throws SchedulerException;
0959:
0960: /**
0961: * <p>
0962: * Add the given <code>{@link TriggerListener}</code> to the <code>Scheduler</code>'s
0963: * <i>global</i> list.
0964: * </p>
0965: *
0966: * <p>
0967: * Listeners in the 'global' list receive notification of execution events
0968: * for ALL <code>{@link Trigger}</code>s.
0969: * </p>
0970: */
0971: void addGlobalTriggerListener(TriggerListener triggerListener)
0972: throws SchedulerException;
0973:
0974: /**
0975: * <p>
0976: * Add the given <code>{@link TriggerListener}</code> to the <code>Scheduler</code>'s
0977: * list, of registered <code>TriggerListener</code>s.
0978: */
0979: void addTriggerListener(TriggerListener triggerListener)
0980: throws SchedulerException;
0981:
0982: /**
0983: * <p>
0984: * Remove the given <code>{@link TriggerListener}</code> from the <code>Scheduler</code>'s
0985: * list of <i>global</i> listeners.
0986: * </p>
0987: *
0988: * @return true if the identifed listener was found in the list, and
0989: * removed.
0990: *
0991: * @deprecated Use <code>{@link #removeGlobalTriggerListener(String)}</code>
0992: */
0993: boolean removeGlobalTriggerListener(TriggerListener triggerListener)
0994: throws SchedulerException;
0995:
0996: /**
0997: * <p>
0998: * Remove the identifed <code>{@link TriggerListener}</code> from the <code>Scheduler</code>'s
0999: * list of <i>global</i> listeners.
1000: * </p>
1001: *
1002: * @return true if the identifed listener was found in the list, and
1003: * removed.
1004: */
1005: boolean removeGlobalTriggerListener(String name)
1006: throws SchedulerException;
1007:
1008: /**
1009: * <p>
1010: * Remove the identifed <code>{@link TriggerListener}</code> from the
1011: * <code>Scheduler</code>'s list of registered listeners.
1012: * </p>
1013: *
1014: * @return true if the identifed listener was found in the list, and
1015: * removed.
1016: */
1017: boolean removeTriggerListener(String name)
1018: throws SchedulerException;
1019:
1020: /**
1021: * <p>
1022: * Get a List containing all of the <code>{@link TriggerListener}</code>
1023: * s in the <code>Scheduler</code>'s<i>global</i> list.
1024: * </p>
1025: */
1026: List getGlobalTriggerListeners() throws SchedulerException;
1027:
1028: /**
1029: * <p>
1030: * Get a Set containing the names of all the <i>non-global</i><code>{@link TriggerListener}</code>
1031: * s registered with the <code>Scheduler</code>.
1032: * </p>
1033: */
1034: Set getTriggerListenerNames() throws SchedulerException;
1035:
1036: /**
1037: * <p>
1038: * Get the <i>global</i><code>{@link TriggerListener}</code> that
1039: * has the given name.
1040: * </p>
1041: */
1042: TriggerListener getGlobalTriggerListener(String name)
1043: throws SchedulerException;
1044:
1045: /**
1046: * <p>
1047: * Get the <i>non-global</i><code>{@link TriggerListener}</code> that
1048: * has the given name.
1049: * </p>
1050: */
1051: TriggerListener getTriggerListener(String name)
1052: throws SchedulerException;
1053:
1054: /**
1055: * <p>
1056: * Register the given <code>{@link SchedulerListener}</code> with the
1057: * <code>Scheduler</code>.
1058: * </p>
1059: */
1060: void addSchedulerListener(SchedulerListener schedulerListener)
1061: throws SchedulerException;
1062:
1063: /**
1064: * <p>
1065: * Remove the given <code>{@link SchedulerListener}</code> from the
1066: * <code>Scheduler</code>.
1067: * </p>
1068: *
1069: * @return true if the identifed listener was found in the list, and
1070: * removed.
1071: */
1072: boolean removeSchedulerListener(SchedulerListener schedulerListener)
1073: throws SchedulerException;
1074:
1075: /**
1076: * <p>
1077: * Get a List containing all of the <code>{@link SchedulerListener}</code>
1078: * s registered with the <code>Scheduler</code>.
1079: * </p>
1080: */
1081: List getSchedulerListeners() throws SchedulerException;
1082:
1083: }
|