Home » quartz-1.6.0 » org » quartz » [javadoc | source]

    1   
    2   /* 
    3    * Copyright 2004-2005 OpenSymphony 
    4    * 
    5    * Licensed under the Apache License, Version 2.0 (the "License"); you may not 
    6    * use this file except in compliance with the License. You may obtain a copy 
    7    * of the License at 
    8    * 
    9    *   http://www.apache.org/licenses/LICENSE-2.0 
   10    *   
   11    * Unless required by applicable law or agreed to in writing, software 
   12    * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 
   13    * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 
   14    * License for the specific language governing permissions and limitations 
   15    * under the License.
   16    * 
   17    */
   18   
   19   /*
   20    * Previously Copyright (c) 2001-2004 James House
   21    */
   22   package org.quartz;
   23   
   24   import java.util.Date;
   25   import java.util.List;
   26   import java.util.Set;
   27   
   28   import org.quartz.spi.JobFactory;
   29   
   30   /**
   31    * <p>
   32    * This is the main interface of a Quartz Scheduler.
   33    * </p>
   34    * 
   35    * <p>
   36    * A <code>Scheduler</code> maintains a registery of <code>{@link org.quartz.JobDetail}</code>
   37    * s and <code>{@link Trigger}</code>s. Once registered, the <code>Scheduler</code>
   38    * is responible for executing <code>Job</code> s when their associated
   39    * <code>Trigger</code> s fire (when their scheduled time arrives).
   40    * </p>
   41    * 
   42    * <p>
   43    * <code>Scheduler</code> instances are produced by a <code>{@link SchedulerFactory}</code>.
   44    * A scheduler that has already been created/initialized can be found and used
   45    * through the same factory that produced it. After a <code>Scheduler</code>
   46    * has been created, it is in "stand-by" mode, and must have its 
   47    * <code>start()</code> method called before it will fire any <code>Job</code>s.
   48    * </p>
   49    * 
   50    * <p>
   51    * <code>Job</code> s are to be created by the 'client program', by defining
   52    * a class that implements the <code>{@link org.quartz.Job}</code>
   53    * interface. <code>{@link JobDetail}</code> objects are then created (also
   54    * by the client) to define a individual instances of the <code>Job</code>.
   55    * <code>JobDetail</code> instances can then be registered with the <code>Scheduler</code>
   56    * via the <code>scheduleJob(JobDetail, Trigger)</code> or <code>addJob(JobDetail, boolean)</code>
   57    * method.
   58    * </p>
   59    * 
   60    * <p>
   61    * <code>Trigger</code> s can then be defined to fire individual <code>Job</code>
   62    * instances based on given schedules. <code>SimpleTrigger</code> s are most
   63    * useful for one-time firings, or firing at an exact moment in time, with N
   64    * repeats with a given delay between them. <code>CronTrigger</code> s allow
   65    * scheduling based on time of day, day of week, day of month, and month of
   66    * year.
   67    * </p>
   68    * 
   69    * <p>
   70    * <code>Job</code> s and <code>Trigger</code> s have a name and group
   71    * associated with them, which should uniquely identify them within a single
   72    * <code>{@link Scheduler}</code>. The 'group' feature may be useful for
   73    * creating logical groupings or categorizations of <code>Jobs</code> s and
   74    * <code>Triggers</code>s. If you don't have need for assigning a group to a
   75    * given <code>Jobs</code> of <code>Triggers</code>, then you can use the
   76    * <code>DEFAULT_GROUP</code> constant defined on this interface.
   77    * </p>
   78    * 
   79    * <p>
   80    * Stored <code>Job</code> s can also be 'manually' triggered through the use
   81    * of the <code>triggerJob(String jobName, String jobGroup)</code> function.
   82    * </p>
   83    * 
   84    * <p>
   85    * Client programs may also be interested in the 'listener' interfaces that are
   86    * available from Quartz. The <code>{@link JobListener}</code> interface
   87    * provides notifications of <code>Job</code> executions. The <code>{@link TriggerListener}</code>
   88    * interface provides notifications of <code>Trigger</code> firings. The
   89    * <code>{@link SchedulerListener}</code> interface provides notifications of
   90    * <code>Scheduler</code> events and errors.
   91    * </p>
   92    * 
   93    * <p>
   94    * The setup/configuration of a <code>Scheduler</code> instance is very
   95    * customizable. Please consult the documentation distributed with Quartz.
   96    * </p>
   97    * 
   98    * @see Job
   99    * @see JobDetail
  100    * @see Trigger
  101    * @see JobListener
  102    * @see TriggerListener
  103    * @see SchedulerListener
  104    * 
  105    * @author James House
  106    * @author Sharada Jambula
  107    */
  108   public interface Scheduler {
  109   
  110       /*
  111        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  112        * 
  113        * Constants.
  114        * 
  115        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  116        */
  117   
  118       /**
  119        * <p>
  120        * A (possibly) usefull constant that can be used for specifying the group
  121        * that <code>Job</code> and <code>Trigger</code> instances belong to.
  122        * </p>
  123        */
  124       String DEFAULT_GROUP = "DEFAULT";
  125   
  126       /**
  127        * <p>
  128        * A constant <code>Trigger</code> group name used internally by the
  129        * scheduler - clients should not use the value of this constant
  130        * ("MANUAL_TRIGGER") for the name of a <code>Trigger</code>'s group.
  131        * </p>
  132        */
  133       String DEFAULT_MANUAL_TRIGGERS = "MANUAL_TRIGGER";
  134   
  135       /**
  136        * <p>
  137        * A constant <code>Trigger</code> group name used internally by the
  138        * scheduler - clients should not use the value of this constant
  139        * ("RECOVERING_JOBS") for the name of a <code>Trigger</code>'s group.
  140        * </p>
  141        *
  142        * @see org.quartz.JobDetail#requestsRecovery()
  143        */
  144       String DEFAULT_RECOVERY_GROUP = "RECOVERING_JOBS";
  145   
  146       /**
  147        * <p>
  148        * A constant <code>Trigger</code> group name used internally by the
  149        * scheduler - clients should not use the value of this constant
  150        * ("FAILED_OVER_JOBS") for the name of a <code>Trigger</code>'s group.
  151        * </p>
  152        *
  153        * @see org.quartz.JobDetail#requestsRecovery()
  154        */
  155       String DEFAULT_FAIL_OVER_GROUP = "FAILED_OVER_JOBS";
  156   
  157   
  158       /**
  159        * A constant <code>JobDataMap</code> key that can be used to retrieve the
  160        * name of the original <code>Trigger</code> from a recovery trigger's
  161        * data map in the case of a job recovering after a failed scheduler
  162        * instance.
  163        *
  164        * @see org.quartz.JobDetail#requestsRecovery()
  165        */
  166       String FAILED_JOB_ORIGINAL_TRIGGER_NAME =  "QRTZ_FAILED_JOB_ORIG_TRIGGER_NAME";
  167   
  168       /**
  169        * A constant <code>JobDataMap</code> key that can be used to retrieve the
  170        * group of the original <code>Trigger</code> from a recovery trigger's
  171        * data map in the case of a job recovering after a failed scheduler
  172        * instance.
  173        *
  174        * @see org.quartz.JobDetail#requestsRecovery()
  175        */
  176       String FAILED_JOB_ORIGINAL_TRIGGER_GROUP =  "QRTZ_FAILED_JOB_ORIG_TRIGGER_GROUP";
  177   
  178       /**
  179        * A constant <code>JobDataMap</code> key that can be used to retrieve the
  180        * scheduled fire time of the original <code>Trigger</code> from a recovery
  181        * trigger's data map in the case of a job recovering after a failed scheduler
  182        * instance.
  183        *
  184        * @see org.quartz.JobDetail#requestsRecovery()
  185        */
  186       String FAILED_JOB_ORIGINAL_TRIGGER_FIRETIME_IN_MILLISECONDS =  "QRTZ_FAILED_JOB_ORIG_TRIGGER_FIRETIME_IN_MILLISECONDS_AS_STRING";
  187   
  188   
  189       /*
  190        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  191        * 
  192        * Interface.
  193        * 
  194        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  195        */
  196   
  197       /**
  198        * <p>
  199        * Returns the name of the <code>Scheduler</code>.
  200        * </p>
  201        */
  202       String getSchedulerName() throws SchedulerException;
  203   
  204       /**
  205        * <p>
  206        * Returns the instance Id of the <code>Scheduler</code>.
  207        * </p>
  208        */
  209       String getSchedulerInstanceId() throws SchedulerException;
  210   
  211       /**
  212        * <p>
  213        * Returns the <code>SchedulerContext</code> of the <code>Scheduler</code>.
  214        * </p>
  215        */
  216       SchedulerContext getContext() throws SchedulerException;
  217   
  218       ///////////////////////////////////////////////////////////////////////////
  219       ///
  220       /// Schedululer State Management Methods
  221       ///
  222       ///////////////////////////////////////////////////////////////////////////
  223       
  224       /**
  225        * <p>
  226        * Starts the <code>Scheduler</code>'s threads that fire <code>{@link Trigger}s</code>.
  227        * When a scheduler is first created it is in "stand-by" mode, and will not
  228        * fire triggers.  The scheduler can also be put into stand-by mode by
  229        * calling the <code>standby()</code> method. 
  230        * </p>
  231        * 
  232        * <p>
  233        * The misfire/recovery process will be started, if it is the initial call
  234        * to this method on this scheduler instance.
  235        * </p>
  236        * 
  237        * @throws SchedulerException
  238        *           if <code>shutdown()</code> has been called, or there is an
  239        *           error within the <code>Scheduler</code>.
  240        * 
  241        * @see #standby
  242        * @see #shutdown
  243        */
  244       void start() throws SchedulerException;
  245   
  246       /**
  247        * Whether the scheduler has been started.  
  248        * 
  249        * <p>
  250        * Note: This only reflects whether <code>{@link #start()}</code> has ever
  251        * been called on this Scheduler, so it will return <code>true</code> even 
  252        * if the <code>Scheduler</code> is currently in standby mode or has been 
  253        * since shutdown.
  254        * </p>
  255        * 
  256        * @see #start()
  257        * @see #isShutdown()
  258        * @see #isInStandbyMode()
  259        */    
  260       boolean isStarted() throws SchedulerException;
  261       
  262       /**
  263        * <p>
  264        * Temporarily halts the <code>Scheduler</code>'s firing of <code>{@link Trigger}s</code>.
  265        * </p>
  266        * 
  267        * <p>
  268        * When <code>start()</code> is called (to bring the scheduler out of 
  269        * stand-by mode), trigger misfire instructions will NOT be applied
  270        * during the execution of the <code>start()</code> method - any misfires 
  271        * will be detected immediately afterward (by the <code>JobStore</code>'s 
  272        * normal process).
  273        * </p>
  274        * 
  275        * <p>
  276        * The scheduler is not destroyed, and can be re-started at any time.
  277        * </p>
  278        * 
  279        * @see #start()
  280        * @see #pauseAll()
  281        */
  282       void standby() throws SchedulerException;
  283   
  284       /**
  285        * @deprecated replaced by better-named standby() method.
  286        * @see #standby()
  287        */
  288       void pause() throws SchedulerException;
  289   
  290       /**
  291        * <p>
  292        * Reports whether the <code>Scheduler</code> is in stand-by mode.
  293        * </p>
  294        * 
  295        * @see #standby()
  296        * @see #start()
  297        */
  298       boolean isInStandbyMode() throws SchedulerException;
  299   
  300       /**
  301        * @deprecated
  302        * @see #isInStandbyMode() 
  303        */
  304       boolean isPaused() throws SchedulerException;
  305   
  306       /**
  307        * <p>
  308        * Halts the <code>Scheduler</code>'s firing of <code>{@link Trigger}s</code>,
  309        * and cleans up all resources associated with the Scheduler. Equivalent to
  310        * <code>shutdown(false)</code>.
  311        * </p>
  312        * 
  313        * <p>
  314        * The scheduler cannot be re-started.
  315        * </p>
  316        * 
  317        * @see #shutdown(boolean)
  318        */
  319       void shutdown() throws SchedulerException;
  320   
  321       /**
  322        * <p>
  323        * Halts the <code>Scheduler</code>'s firing of <code>{@link Trigger}s</code>,
  324        * and cleans up all resources associated with the Scheduler.
  325        * </p>
  326        * 
  327        * <p>
  328        * The scheduler cannot be re-started.
  329        * </p>
  330        * 
  331        * @param waitForJobsToComplete
  332        *          if <code>true</code> the scheduler will not allow this method
  333        *          to return until all currently executing jobs have completed.
  334        * 
  335        * @see #shutdown
  336        */
  337       void shutdown(boolean waitForJobsToComplete)
  338           throws SchedulerException;
  339   
  340       /**
  341        * <p>
  342        * Reports whether the <code>Scheduler</code> has been shutdown.
  343        * </p>
  344        */
  345       boolean isShutdown() throws SchedulerException;
  346   
  347       /**
  348        * <p>
  349        * Get a <code>SchedulerMetaData</code> object describiing the settings
  350        * and capabilities of the scheduler instance.
  351        * </p>
  352        * 
  353        * <p>
  354        * Note that the data returned is an 'instantaneous' snap-shot, and that as
  355        * soon as it's returned, the meta data values may be different.
  356        * </p>
  357        */
  358       SchedulerMetaData getMetaData() throws SchedulerException;
  359   
  360       /**
  361        * <p>
  362        * Return a list of <code>JobExecutionContext</code> objects that
  363        * represent all currently executing Jobs in this Scheduler instance.
  364        * </p>
  365        * 
  366        * <p>
  367        * This method is not cluster aware.  That is, it will only return Jobs
  368        * currently executing in this Scheduler instance, not across the entire
  369        * cluster.
  370        * </p>
  371        * 
  372        * <p>
  373        * Note that the list returned is an 'instantaneous' snap-shot, and that as
  374        * soon as it's returned, the true list of executing jobs may be different.
  375        * Also please read the doc associated with <code>JobExecutionContext</code>-
  376        * especially if you're using RMI.
  377        * </p>
  378        * 
  379        * @see JobExecutionContext
  380        */
  381       List getCurrentlyExecutingJobs() throws SchedulerException;
  382   
  383       /**
  384        * <p>
  385        * Set the <code>JobFactory</code> that will be responsible for producing 
  386        * instances of <code>Job</code> classes.
  387        * </p>
  388        * 
  389        * <p>
  390        * JobFactories may be of use to those wishing to have their application
  391        * produce <code>Job</code> instances via some special mechanism, such as to
  392        * give the opertunity for dependency injection.
  393        * </p>
  394        * 
  395        * @see org.quartz.spi.JobFactory
  396        */
  397       void setJobFactory(JobFactory factory) throws SchedulerException;
  398       
  399       ///////////////////////////////////////////////////////////////////////////
  400       ///
  401       /// Scheduling-related Methods
  402       ///
  403       ///////////////////////////////////////////////////////////////////////////
  404   
  405       /**
  406        * <p>
  407        * Add the given <code>{@link org.quartz.JobDetail}</code> to the
  408        * Scheduler, and associate the given <code>{@link Trigger}</code> with
  409        * it.
  410        * </p>
  411        * 
  412        * <p>
  413        * If the given Trigger does not reference any <code>Job</code>, then it
  414        * will be set to reference the Job passed with it into this method.
  415        * </p>
  416        * 
  417        * @throws SchedulerException
  418        *           if the Job or Trigger cannot be added to the Scheduler, or
  419        *           there is an internal Scheduler error.
  420        */
  421       Date scheduleJob(JobDetail jobDetail, Trigger trigger)
  422           throws SchedulerException;
  423   
  424       /**
  425        * <p>
  426        * Schedule the given <code>{@link org.quartz.Trigger}</code> with the
  427        * <code>Job</code> identified by the <code>Trigger</code>'s settings.
  428        * </p>
  429        * 
  430        * @throws SchedulerException
  431        *           if the indicated Job does not exist, or the Trigger cannot be
  432        *           added to the Scheduler, or there is an internal Scheduler
  433        *           error.
  434        */
  435       Date scheduleJob(Trigger trigger) throws SchedulerException;
  436   
  437       /**
  438        * <p>
  439        * Remove the indicated <code>{@link Trigger}</code> from the scheduler.
  440        * </p>
  441        */
  442       boolean unscheduleJob(String triggerName, String groupName)
  443           throws SchedulerException;
  444   
  445       /**
  446        * <p>
  447        * Remove (delete) the <code>{@link org.quartz.Trigger}</code> with the
  448        * given name, and store the new given one - which must be associated
  449        * with the same job (the new trigger must have the job name & group specified) 
  450        * - however, the new trigger need not have the same name as the old trigger.
  451        * </p>
  452        * 
  453        * @param triggerName
  454        *          The name of the <code>Trigger</code> to be replaced.
  455        * @param groupName
  456        *          The group name of the <code>Trigger</code> to be replaced.
  457        * @param newTrigger
  458        *          The new <code>Trigger</code> to be stored.
  459        * @return <code>null</code> if a <code>Trigger</code> with the given
  460        *         name & group was not found and removed from the store, otherwise
  461        *         the first fire time of the newly scheduled trigger.
  462        */
  463       Date rescheduleJob(String triggerName,
  464               String groupName, Trigger newTrigger) throws SchedulerException;
  465   
  466       
  467       /**
  468        * <p>
  469        * Add the given <code>Job</code> to the Scheduler - with no associated
  470        * <code>Trigger</code>. The <code>Job</code> will be 'dormant' until
  471        * it is scheduled with a <code>Trigger</code>, or <code>Scheduler.triggerJob()</code>
  472        * is called for it.
  473        * </p>
  474        * 
  475        * <p>
  476        * The <code>Job</code> must by definition be 'durable', if it is not,
  477        * SchedulerException will be thrown.
  478        * </p>
  479        * 
  480        * @throws SchedulerException
  481        *           if there is an internal Scheduler error, or if the Job is not
  482        *           durable, or a Job with the same name already exists, and
  483        *           <code>replace</code> is <code>false</code>.
  484        */
  485       void addJob(JobDetail jobDetail, boolean replace)
  486           throws SchedulerException;
  487   
  488       /**
  489        * <p>
  490        * Delete the identified <code>Job</code> from the Scheduler - and any
  491        * associated <code>Trigger</code>s.
  492        * </p>
  493        * 
  494        * @return true if the Job was found and deleted.
  495        * @throws SchedulerException
  496        *           if there is an internal Scheduler error.
  497        */
  498       boolean deleteJob(String jobName, String groupName)
  499           throws SchedulerException;
  500   
  501       /**
  502        * <p>
  503        * Trigger the identified <code>{@link org.quartz.JobDetail}</code>
  504        * (execute it now) - the generated trigger will be non-volatile.
  505        * </p>
  506        */
  507       void triggerJob(String jobName, String groupName)
  508           throws SchedulerException;
  509   
  510       /**
  511        * <p>
  512        * Trigger the identified <code>{@link org.quartz.JobDetail}</code>
  513        * (execute it now) - the generated trigger will be volatile.
  514        * </p>
  515        */
  516       void triggerJobWithVolatileTrigger(String jobName, String groupName)
  517           throws SchedulerException;
  518   
  519       /**
  520        * <p>
  521        * Trigger the identified <code>{@link org.quartz.JobDetail}</code>
  522        * (execute it now) - the generated trigger will be non-volatile.
  523        * </p>
  524        * 
  525        * @param jobName the name of the Job to trigger
  526        * @param groupName the group name of the Job to trigger
  527        * @param data the (possibly <code>null</code>) JobDataMap to be 
  528        * associated with the trigger that fires the job immediately. 
  529        */
  530       void triggerJob(String jobName, String groupName, JobDataMap data)
  531           throws SchedulerException;
  532   
  533       /**
  534        * <p>
  535        * Trigger the identified <code>{@link org.quartz.JobDetail}</code>
  536        * (execute it now) - the generated trigger will be volatile.
  537        * </p>
  538        * 
  539        * @param jobName the name of the Job to trigger
  540        * @param groupName the group name of the Job to trigger
  541        * @param data the (possibly <code>null</code>) JobDataMap to be 
  542        * associated with the trigger that fires the job immediately. 
  543        */
  544       void triggerJobWithVolatileTrigger(String jobName, String groupName, JobDataMap data)
  545           throws SchedulerException;
  546   
  547       /**
  548        * <p>
  549        * Pause the <code>{@link org.quartz.JobDetail}</code> with the given
  550        * name - by pausing all of its current <code>Trigger</code>s.
  551        * </p>
  552        * 
  553        * @see #resumeJob(String, String)
  554        */
  555       void pauseJob(String jobName, String groupName)
  556           throws SchedulerException;
  557   
  558       /**
  559        * <p>
  560        * Pause all of the <code>{@link org.quartz.JobDetail}s</code> in the
  561        * given group - by pausing all of their <code>Trigger</code>s.
  562        * </p>
  563        * 
  564        * <p>
  565        * The Scheduler will "remember" that the group is paused, and impose the
  566        * pause on any new jobs that are added to the group while the group is
  567        * paused.
  568        * </p>
  569        * 
  570        * @see #resumeJobGroup(String)
  571        */
  572       void pauseJobGroup(String groupName) throws SchedulerException;
  573   
  574       /**
  575        * <p>
  576        * Pause the <code>{@link Trigger}</code> with the given name.
  577        * </p>
  578        * 
  579        * @see #resumeTrigger(String, String)
  580        */
  581       void pauseTrigger(String triggerName, String groupName)
  582           throws SchedulerException;
  583   
  584       /**
  585        * <p>
  586        * Pause all of the <code>{@link Trigger}s</code> in the given group.
  587        * </p>
  588        * 
  589        * <p>
  590        * The Scheduler will "remember" that the group is paused, and impose the
  591        * pause on any new triggers that are added to the group while the group is
  592        * paused.
  593        * </p>
  594        * 
  595        * @see #resumeTriggerGroup(String)
  596        */
  597       void pauseTriggerGroup(String groupName) throws SchedulerException;
  598   
  599       /**
  600        * <p>
  601        * Resume (un-pause) the <code>{@link org.quartz.JobDetail}</code> with
  602        * the given name.
  603        * </p>
  604        * 
  605        * <p>
  606        * If any of the <code>Job</code>'s<code>Trigger</code> s missed one
  607        * or more fire-times, then the <code>Trigger</code>'s misfire
  608        * instruction will be applied.
  609        * </p>
  610        * 
  611        * @see #pauseJob(String, String)
  612        */
  613       void resumeJob(String jobName, String groupName)
  614           throws SchedulerException;
  615   
  616       /**
  617        * <p>
  618        * Resume (un-pause) all of the <code>{@link org.quartz.JobDetail}s</code>
  619        * in the given group.
  620        * </p>
  621        * 
  622        * <p>
  623        * If any of the <code>Job</code> s had <code>Trigger</code> s that
  624        * missed one or more fire-times, then the <code>Trigger</code>'s
  625        * misfire instruction will be applied.
  626        * </p>
  627        * 
  628        * @see #pauseJobGroup(String)
  629        */
  630       void resumeJobGroup(String groupName) throws SchedulerException;
  631   
  632       /**
  633        * <p>
  634        * Resume (un-pause) the <code>{@link Trigger}</code> with the given
  635        * name.
  636        * </p>
  637        * 
  638        * <p>
  639        * If the <code>Trigger</code> missed one or more fire-times, then the
  640        * <code>Trigger</code>'s misfire instruction will be applied.
  641        * </p>
  642        * 
  643        * @see #pauseTrigger(String, String)
  644        */
  645       void resumeTrigger(String triggerName, String groupName)
  646           throws SchedulerException;
  647   
  648       /**
  649        * <p>
  650        * Resume (un-pause) all of the <code>{@link Trigger}s</code> in the
  651        * given group.
  652        * </p>
  653        * 
  654        * <p>
  655        * If any <code>Trigger</code> missed one or more fire-times, then the
  656        * <code>Trigger</code>'s misfire instruction will be applied.
  657        * </p>
  658        * 
  659        * @see #pauseTriggerGroup(String)
  660        */
  661       void resumeTriggerGroup(String groupName) throws SchedulerException;
  662   
  663       /**
  664        * <p>
  665        * Pause all triggers - similar to calling <code>pauseTriggerGroup(group)</code>
  666        * on every group, however, after using this method <code>resumeAll()</code> 
  667        * must be called to clear the scheduler's state of 'remembering' that all 
  668        * new triggers will be paused as they are added. 
  669        * </p>
  670        * 
  671        * <p>
  672        * When <code>resumeAll()</code> is called (to un-pause), trigger misfire
  673        * instructions WILL be applied.
  674        * </p>
  675        * 
  676        * @see #resumeAll()
  677        * @see #pauseTriggerGroup(String)
  678        * @see #standby()
  679        */
  680       void pauseAll() throws SchedulerException;
  681   
  682       /**
  683        * <p>
  684        * Resume (un-pause) all triggers - similar to calling 
  685        * <code>resumeTriggerGroup(group)</code> on every group.
  686        * </p>
  687        * 
  688        * <p>
  689        * If any <code>Trigger</code> missed one or more fire-times, then the
  690        * <code>Trigger</code>'s misfire instruction will be applied.
  691        * </p>
  692        * 
  693        * @see #pauseAll()
  694        */
  695       void resumeAll() throws SchedulerException;
  696   
  697       /**
  698        * <p>
  699        * Get the names of all known <code>{@link org.quartz.JobDetail}</code>
  700        * groups.
  701        * </p>
  702        */
  703       String[] getJobGroupNames() throws SchedulerException;
  704   
  705       /**
  706        * <p>
  707        * Get the names of all the <code>{@link org.quartz.JobDetail}s</code>
  708        * in the given group.
  709        * </p>
  710        */
  711       String[] getJobNames(String groupName) throws SchedulerException;
  712   
  713       /**
  714        * <p>
  715        * Get all <code>{@link Trigger}</code> s that are associated with the
  716        * identified <code>{@link org.quartz.JobDetail}</code>.
  717        * </p>
  718        */
  719       Trigger[] getTriggersOfJob(String jobName, String groupName)
  720           throws SchedulerException;
  721   
  722       /**
  723        * <p>
  724        * Get the names of all known <code>{@link Trigger}</code> groups.
  725        * </p>
  726        */
  727       String[] getTriggerGroupNames() throws SchedulerException;
  728   
  729       /**
  730        * <p>
  731        * Get the names of all the <code>{@link Trigger}s</code> in the given
  732        * group.
  733        * </p>
  734        */
  735       String[] getTriggerNames(String groupName) throws SchedulerException;
  736   
  737       /**
  738        * <p>
  739        * Get the names of all <code>{@link Trigger}</code> groups that are paused.
  740        * </p>
  741        */
  742       Set getPausedTriggerGroups() throws SchedulerException;
  743       
  744       /**
  745        * <p>
  746        * Get the <code>{@link JobDetail}</code> for the <code>Job</code>
  747        * instance with the given name and group.
  748        * </p>
  749        */
  750       JobDetail getJobDetail(String jobName, String jobGroup)
  751           throws SchedulerException;
  752   
  753       /**
  754        * <p>
  755        * Get the <code>{@link Trigger}</code> instance with the given name and
  756        * group.
  757        * </p>
  758        */
  759       Trigger getTrigger(String triggerName, String triggerGroup)
  760           throws SchedulerException;
  761   
  762       /**
  763        * <p>
  764        * Get the current state of the identified <code>{@link Trigger}</code>.
  765        * </p>
  766        * 
  767        * @see Trigger#STATE_NORMAL
  768        * @see Trigger#STATE_PAUSED
  769        * @see Trigger#STATE_COMPLETE
  770        * @see Trigger#STATE_ERROR
  771        * @see Trigger#STATE_BLOCKED
  772        * @see Trigger#STATE_NONE
  773        */
  774       int getTriggerState(String triggerName, String triggerGroup)
  775           throws SchedulerException;
  776   
  777       /**
  778        * <p>
  779        * Add (register) the given <code>Calendar</code> to the Scheduler.
  780        * </p>
  781        * 
  782        * @param updateTriggers whether or not to update existing triggers that
  783        * referenced the already existing calendar so that they are 'correct'
  784        * based on the new trigger. 
  785        * 
  786        *  
  787        * @throws SchedulerException
  788        *           if there is an internal Scheduler error, or a Calendar with
  789        *           the same name already exists, and <code>replace</code> is
  790        *           <code>false</code>.
  791        */
  792       void addCalendar(String calName, Calendar calendar, boolean replace, boolean updateTriggers)
  793           throws SchedulerException;
  794   
  795       /**
  796        * <p>
  797        * Delete the identified <code>Calendar</code> from the Scheduler.
  798        * </p>
  799        * 
  800        * @return true if the Calendar was found and deleted.
  801        * @throws SchedulerException
  802        *           if there is an internal Scheduler error.
  803        */
  804       boolean deleteCalendar(String calName) throws SchedulerException;
  805   
  806       /**
  807        * <p>
  808        * Get the <code>{@link Calendar}</code> instance with the given name.
  809        * </p>
  810        */
  811       Calendar getCalendar(String calName) throws SchedulerException;
  812   
  813       /**
  814        * <p>
  815        * Get the names of all registered <code>{@link Calendar}s</code>.
  816        * </p>
  817        */
  818       String[] getCalendarNames() throws SchedulerException;
  819   
  820       /**
  821        * <p>
  822        * Request the interruption, within this Scheduler instance, of all 
  823        * currently executing instances of the identified <code>Job</code>, which 
  824        * must be an implementor of the <code>InterruptableJob</code> interface.
  825        * </p>
  826        * 
  827        * <p>
  828        * If more than one instance of the identified job is currently executing,
  829        * the <code>InterruptableJob#interrupt()</code> method will be called on
  830        * each instance.  However, there is a limitation that in the case that  
  831        * <code>interrupt()</code> on one instances throws an exception, all 
  832        * remaining  instances (that have not yet been interrupted) will not have 
  833        * their <code>interrupt()</code> method called.
  834        * </p>
  835        * 
  836        * <p>
  837        * If you wish to interrupt a specific instance of a job (when more than
  838        * one is executing) you can do so by calling 
  839        * <code>{@link #getCurrentlyExecutingJobs()}</code> to obtain a handle 
  840        * to the job instance, and then invoke <code>interrupt()</code> on it
  841        * yourself.
  842        * </p>
  843        * 
  844        * <p>
  845        * This method is not cluster aware.  That is, it will only interrupt 
  846        * instances of the identified InterruptableJob currently executing in this 
  847        * Scheduler instance, not across the entire cluster.
  848        * </p>
  849        * 
  850        * @param jobName
  851        * @param groupName
  852        * @return true is at least one instance of the identified job was found
  853        * and interrupted.
  854        * @throws UnableToInterruptJobException if the job does not implement
  855        * <code>InterruptableJob</code>, or there is an exception while 
  856        * interrupting the job.
  857        * @see InterruptableJob#interrupt()
  858        * @see #getCurrentlyExecutingJobs()
  859        */
  860       boolean interrupt(String jobName, String groupName) throws UnableToInterruptJobException;
  861       
  862       ///////////////////////////////////////////////////////////////////////////
  863       ///
  864       /// Listener-related Methods
  865       ///
  866       ///////////////////////////////////////////////////////////////////////////
  867   
  868       /**
  869        * <p>
  870        * Add the given <code>{@link JobListener}</code> to the <code>Scheduler</code>'s
  871        * <i>global</i> list.
  872        * </p>
  873        * 
  874        * <p>
  875        * Listeners in the 'global' list receive notification of execution events
  876        * for ALL <code>{@link org.quartz.JobDetail}</code>s.
  877        * </p>
  878        */
  879       void addGlobalJobListener(JobListener jobListener)
  880           throws SchedulerException;
  881   
  882       /**
  883        * <p>
  884        * Add the given <code>{@link JobListener}</code> to the <code>Scheduler</code>'s
  885        * list, of registered <code>JobListener</code>s.
  886        */
  887       void addJobListener(JobListener jobListener)
  888           throws SchedulerException;
  889   
  890       /**
  891        * <p>
  892        * Remove the given <code>{@link JobListener}</code> from the <code>Scheduler</code>'s
  893        * list of <i>global</i> listeners.
  894        * </p>
  895        * 
  896        * @return true if the identifed listener was found in the list, and
  897        *         removed.
  898        *         
  899        * @deprecated Use <code>{@link #removeGlobalJobListener(String)}</code>
  900        */
  901       boolean removeGlobalJobListener(JobListener jobListener)
  902           throws SchedulerException;
  903       
  904       /**
  905        * <p>
  906        * Remove the identifed <code>{@link JobListener}</code> from the <code>Scheduler</code>'s
  907        * list of <i>global</i> listeners.
  908        * </p>
  909        * 
  910        * @return true if the identifed listener was found in the list, and
  911        *         removed.
  912        */
  913       boolean removeGlobalJobListener(String name)
  914           throws SchedulerException;
  915   
  916       /**
  917        * <p>
  918        * Remove the identifed <code>{@link JobListener}</code> from the <code>Scheduler</code>'s
  919        * list of registered listeners.
  920        * </p>
  921        * 
  922        * @return true if the identifed listener was found in the list, and
  923        *         removed.
  924        */
  925       boolean removeJobListener(String name) throws SchedulerException;
  926   
  927       /**
  928        * <p>
  929        * Get a List containing all of the <code>{@link JobListener}</code> s in
  930        * the <code>Scheduler</code>'s<i>global</i> list.
  931        * </p>
  932        */
  933       List getGlobalJobListeners() throws SchedulerException;
  934   
  935       /**
  936        * <p>
  937        * Get a Set containing the names of all the <i>non-global</i><code>{@link JobListener}</code>
  938        * s registered with the <code>Scheduler</code>.
  939        * </p>
  940        */
  941       Set getJobListenerNames() throws SchedulerException;
  942   
  943       /**
  944        * <p>
  945        * Get the <i>global</i><code>{@link JobListener}</code> that has
  946        * the given name.
  947        * </p>
  948        */
  949       JobListener getGlobalJobListener(String name) throws SchedulerException;
  950       
  951       /**
  952        * <p>
  953        * Get the <i>non-global</i><code>{@link JobListener}</code> that has
  954        * the given name.
  955        * </p>
  956        */
  957       JobListener getJobListener(String name) throws SchedulerException;
  958   
  959       /**
  960        * <p>
  961        * Add the given <code>{@link TriggerListener}</code> to the <code>Scheduler</code>'s
  962        * <i>global</i> list.
  963        * </p>
  964        * 
  965        * <p>
  966        * Listeners in the 'global' list receive notification of execution events
  967        * for ALL <code>{@link Trigger}</code>s.
  968        * </p>
  969        */
  970       void addGlobalTriggerListener(TriggerListener triggerListener)
  971           throws SchedulerException;
  972   
  973       /**
  974        * <p>
  975        * Add the given <code>{@link TriggerListener}</code> to the <code>Scheduler</code>'s
  976        * list, of registered <code>TriggerListener</code>s.
  977        */
  978       void addTriggerListener(TriggerListener triggerListener)
  979           throws SchedulerException;
  980   
  981       /**
  982        * <p>
  983        * Remove the given <code>{@link TriggerListener}</code> from the <code>Scheduler</code>'s
  984        * list of <i>global</i> listeners.
  985        * </p>
  986        * 
  987        * @return true if the identifed listener was found in the list, and
  988        *         removed.
  989        *         
  990        * @deprecated Use <code>{@link #removeGlobalTriggerListener(String)}</code>
  991        */
  992       boolean removeGlobalTriggerListener(TriggerListener triggerListener)
  993           throws SchedulerException;
  994   
  995       /**
  996        * <p>
  997        * Remove the identifed <code>{@link TriggerListener}</code> from the <code>Scheduler</code>'s
  998        * list of <i>global</i> listeners.
  999        * </p>
 1000        * 
 1001        * @return true if the identifed listener was found in the list, and
 1002        *         removed.
 1003        */
 1004       boolean removeGlobalTriggerListener(String name)
 1005           throws SchedulerException;
 1006   
 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) throws SchedulerException;
 1018   
 1019       /**
 1020        * <p>
 1021        * Get a List containing all of the <code>{@link TriggerListener}</code>
 1022        * s in the <code>Scheduler</code>'s<i>global</i> list.
 1023        * </p>
 1024        */
 1025       List getGlobalTriggerListeners() throws SchedulerException;
 1026   
 1027       /**
 1028        * <p>
 1029        * Get a Set containing the names of all the <i>non-global</i><code>{@link TriggerListener}</code>
 1030        * s registered with the <code>Scheduler</code>.
 1031        * </p>
 1032        */
 1033       Set getTriggerListenerNames() throws SchedulerException;
 1034   
 1035       /**
 1036        * <p>
 1037        * Get the <i>global</i><code>{@link TriggerListener}</code> that
 1038        * has the given name.
 1039        * </p>
 1040        */
 1041       TriggerListener getGlobalTriggerListener(String name)
 1042           throws SchedulerException;
 1043       
 1044       /**
 1045        * <p>
 1046        * Get the <i>non-global</i><code>{@link TriggerListener}</code> that
 1047        * has the given name.
 1048        * </p>
 1049        */
 1050       TriggerListener getTriggerListener(String name)
 1051           throws SchedulerException;
 1052   
 1053       /**
 1054        * <p>
 1055        * Register the given <code>{@link SchedulerListener}</code> with the
 1056        * <code>Scheduler</code>.
 1057        * </p>
 1058        */
 1059       void addSchedulerListener(SchedulerListener schedulerListener)
 1060           throws SchedulerException;
 1061   
 1062       /**
 1063        * <p>
 1064        * Remove the given <code>{@link SchedulerListener}</code> from the
 1065        * <code>Scheduler</code>.
 1066        * </p>
 1067        * 
 1068        * @return true if the identifed listener was found in the list, and
 1069        *         removed.
 1070        */
 1071       boolean removeSchedulerListener(SchedulerListener schedulerListener)
 1072           throws SchedulerException;
 1073   
 1074       /**
 1075        * <p>
 1076        * Get a List containing all of the <code>{@link SchedulerListener}</code>
 1077        * s registered with the <code>Scheduler</code>.
 1078        * </p>
 1079        */
 1080       List getSchedulerListeners() throws SchedulerException;
 1081   
 1082   
 1083   }

Home » quartz-1.6.0 » org » quartz » [javadoc | source]