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.Calendar;
   25   import java.util.Date;
   26   import java.util.LinkedList;
   27   import java.util.List;
   28   import java.util.TimeZone;
   29   
   30   /**
   31    * <p>
   32    * Convenience and utility methods for simplifying the construction and
   33    * configuration of <code>{@link Trigger}s</code>.
   34    * </p>
   35    * 
   36    * <p>
   37    * Please submit suggestions for additional convenience methods to either the
   38    * Quartz user forum or the developer's mail list at
   39    * <a href="http://www.sourceforge.net/projects/quartz">source forge</a>.
   40    * </p>
   41    * 
   42    * @see CronTrigger
   43    * @see SimpleTrigger
   44    * 
   45    * @author James House
   46    */
   47   public class TriggerUtils {
   48   
   49       /*
   50        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   51        * 
   52        * Constants.
   53        * 
   54        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   55        */
   56   
   57       public static final int SUNDAY = 1;
   58   
   59       public static final int MONDAY = 2;
   60   
   61       public static final int TUESDAY = 3;
   62   
   63       public static final int WEDNESDAY = 4;
   64   
   65       public static final int THURSDAY = 5;
   66   
   67       public static final int FRIDAY = 6;
   68   
   69       public static final int SATURDAY = 7;
   70   
   71       public static final int LAST_DAY_OF_MONTH = -1;
   72   
   73       public static final long MILLISECONDS_IN_MINUTE = 60l * 1000l;
   74   
   75       public static final long MILLISECONDS_IN_HOUR = 60l * 60l * 1000l;
   76   
   77       public static final long SECONDS_IN_DAY = 24l * 60l * 60L;
   78   
   79       public static final long MILLISECONDS_IN_DAY = SECONDS_IN_DAY * 1000l;
   80   
   81       /**
   82        * Private constructor because this is a pure utility class.
   83        */
   84       private TriggerUtils() {
   85       }
   86       
   87       /*
   88        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   89        * 
   90        * Interface.
   91        * 
   92        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   93        */
   94   
   95       private static void validateDayOfWeek(int dayOfWeek) {
   96           if (dayOfWeek < SUNDAY || dayOfWeek > SATURDAY) {
   97               throw new IllegalArgumentException("Invalid day of week.");
   98           }
   99       }
  100   
  101       private static void validateHour(int hour) {
  102           if (hour < 0 || hour > 23) {
  103               throw new IllegalArgumentException(
  104                       "Invalid hour (must be >= 0 and <= 23).");
  105           }
  106       }
  107   
  108       private static void validateMinute(int minute) {
  109           if (minute < 0 || minute > 59) {
  110               throw new IllegalArgumentException(
  111                       "Invalid minute (must be >= 0 and <= 59).");
  112           }
  113       }
  114   
  115       private static void validateSecond(int second) {
  116           if (second < 0 || second > 59) {
  117               throw new IllegalArgumentException(
  118                       "Invalid second (must be >= 0 and <= 59).");
  119           }
  120       }
  121   
  122       private static void validateDayOfMonth(int day) {
  123           if ((day < 1 || day > 31) && day != LAST_DAY_OF_MONTH) {
  124               throw new IllegalArgumentException("Invalid day of month.");
  125           }
  126       }
  127   
  128       private static void validateMonth(int month) {
  129           if (month < 1 || month > 12) {
  130               throw new IllegalArgumentException(
  131                       "Invalid month (must be >= 1 and <= 12.");
  132           }
  133       }
  134   
  135       private static void validateYear(int year) {
  136           if (year < 1970 || year > 2099) {
  137               throw new IllegalArgumentException(
  138                       "Invalid year (must be >= 1970 and <= 2099.");
  139           }
  140       }
  141   
  142       /**
  143        * <p>
  144        * Set the given <code>Trigger</code>'s name to the given value, and its
  145        * group to the default group (<code>Scheduler.DEFAULT_GROUP</code>).
  146        * </p>
  147        * 
  148        * @param trig the tigger to change name to 
  149        * @param name the new trigger name
  150        */
  151       public static void setTriggerIdentity(Trigger trig, String name) {
  152           setTriggerIdentity(trig, name, Scheduler.DEFAULT_GROUP);
  153       }
  154   
  155       /**
  156        * <p>
  157        * Set the given <code>Trigger</code>'s name to the given value, and its
  158        * group to the given group.
  159        * </p>
  160        * 
  161        * @param trig the tigger to change name to 
  162        * @param name the new trigger name
  163        * @param group the new trigger group
  164        */
  165       public static void setTriggerIdentity(
  166               Trigger trig, String name, String group) {
  167           trig.setName(name);
  168           trig.setGroup(group);
  169       }
  170   
  171       /**
  172        * <p>
  173        * Make a trigger that will fire every day at the given time.
  174        * </p>
  175        * 
  176        * <p>
  177        * The generated trigger will not have its name, group,
  178        * or end-time set.  The Start time defaults to 'now'.
  179        * </p>
  180        * 
  181        * @param hour the hour (0-23) upon which to fire
  182        * @param minute the minute (0-59) upon which to fire
  183        * @return the new trigger
  184        */
  185       public static Trigger makeDailyTrigger(int hour, int minute) {
  186           validateHour(hour);
  187           validateMinute(minute);
  188   
  189           CronTrigger trig = new CronTrigger();
  190   
  191           try {
  192               trig.setCronExpression("0 " + minute + " " + hour + " ? * *");
  193           } catch (Exception ignore) {
  194               return null; /* never happens... */
  195           }
  196   
  197           trig.setStartTime(new Date());
  198           
  199           return trig;
  200       }
  201   
  202       /**
  203        * <p>
  204        * Make a trigger that will fire every day at the given time.
  205        * </p>
  206        * 
  207        * <p>
  208        * The generated trigger will not have its group or end-time set.  
  209        * The Start time defaults to 'now'.
  210        * </p>
  211        * 
  212        * @param trigName the trigger's name 
  213        * @param hour the hour (0-23) upon which to fire
  214        * @param minute the minute (0-59) upon which to fire
  215        * @return the newly created trigger
  216        */
  217       public static Trigger makeDailyTrigger(
  218               String trigName, int hour, int minute) {
  219           Trigger trig = makeDailyTrigger(hour, minute);
  220           trig.setName(trigName);
  221           return trig;
  222       }
  223       
  224       /**
  225        * <p>
  226        * Make a trigger that will fire every week at the given day and time.
  227        * </p>
  228        * 
  229        * <p>
  230        * The generated trigger will not have its name, group,
  231        * or end-time set.  The Start time defaults to 'now'.
  232        * </p>
  233        * 
  234        * @param dayOfWeek (1-7) the day of week upon which to fire
  235        * @param hour the hour (0-23) upon which to fire
  236        * @param minute the minute (0-59) upon which to fire
  237        * @return the new trigger
  238        * 
  239        * @see #SUNDAY
  240        * @see #MONDAY
  241        * @see #TUESDAY
  242        * @see #WEDNESDAY
  243        * @see #THURSDAY
  244        * @see #FRIDAY
  245        * @see #SATURDAY
  246        */
  247       public static Trigger makeWeeklyTrigger(
  248               int dayOfWeek, int hour, int minute) {
  249           validateDayOfWeek(dayOfWeek);
  250           validateHour(hour);
  251           validateMinute(minute);
  252   
  253           CronTrigger trig = new CronTrigger();
  254   
  255           try {
  256               trig.setCronExpression("0 " + minute + " " + hour + " ? * "
  257                       + dayOfWeek);
  258           } catch (Exception ignore) {
  259               return null; /* never happens... */
  260           }
  261           
  262           trig.setStartTime(new Date());
  263   
  264           return trig;
  265       }
  266   
  267       /**
  268        * <p>
  269        * Make a trigger that will fire every week at the given day and time.
  270        * </p>
  271        * 
  272        * <p>
  273        * The generated trigger will not have its group,
  274        * or end-time set.  The Start time defaults to 'now'.
  275        * </p>
  276        * 
  277        * @param trigName the trigger's name
  278        * @param dayOfWeek (1-7) the day of week upon which to fire
  279        * @param hour the hour (0-23) upon which to fire
  280        * @param minute the minute (0-59) upon which to fire
  281        * @return the newly created trigger
  282        * 
  283        * @see #SUNDAY
  284        * @see #MONDAY
  285        * @see #TUESDAY
  286        * @see #WEDNESDAY
  287        * @see #THURSDAY
  288        * @see #FRIDAY
  289        * @see #SATURDAY
  290        */
  291       public static Trigger makeWeeklyTrigger(
  292               String trigName, int dayOfWeek, int hour, int minute) {
  293           Trigger trig = makeWeeklyTrigger(dayOfWeek, hour, minute);
  294           trig.setName(trigName);
  295           return trig;
  296       }
  297       
  298       
  299       /**
  300        * <p>
  301        * Make a trigger that will fire every month at the given day and time.
  302        * </p>
  303        * 
  304        * <p>
  305        * The generated trigger will not have its name, group,
  306        * or end-time set.  The Start time defaults to 'now'.
  307        * </p>
  308        * 
  309        * <p>
  310        * If the day of the month specified does not occur in a given month, a
  311        * firing will not occur that month. (i.e. if dayOfMonth is specified as
  312        * 31, no firing will occur in the months of the year with fewer than 31
  313        * days).
  314        * </p>
  315        * 
  316        * @param dayOfMonth (1-31, or -1) the day of week upon which to fire
  317        * @param hour the hour (0-23) upon which to fire
  318        * @param minute the minute (0-59) upon which to fire
  319        * @return the newly created trigger
  320        */
  321       public static Trigger makeMonthlyTrigger(
  322               int dayOfMonth, int hour, int minute) {
  323           validateDayOfMonth(dayOfMonth);
  324           validateHour(hour);
  325           validateMinute(minute);
  326   
  327           CronTrigger trig = new CronTrigger();
  328   
  329           try {
  330               if (dayOfMonth != LAST_DAY_OF_MONTH) { 
  331                   trig.setCronExpression("0 " + minute + " " + hour + " " + dayOfMonth + " * ?");
  332               } else {
  333                   trig.setCronExpression("0 " + minute + " " + hour + " L * ?");
  334               }
  335           } catch (Exception ignore) {
  336               return null; /* never happens... */
  337           }
  338           
  339           trig.setStartTime(new Date());
  340   
  341           return trig;
  342       }
  343   
  344       /**
  345        * <p>
  346        * Make a trigger that will fire every month at the given day and time.
  347        * </p>
  348        * 
  349        * <p>
  350        * The generated trigger will not have its group,
  351        * or end-time set.  The Start time defaults to 'now'.
  352        * </p>
  353        * 
  354        * <p>
  355        * If the day of the month specified does not occur in a given month, a
  356        * firing will not occur that month. (i.e. if dayOfMonth is specified as
  357        * 31, no firing will occur in the months of the year with fewer than 31
  358        * days).
  359        * </p>
  360        * 
  361        * @param trigName the trigger's name
  362        * @param dayOfMonth (1-31, or -1) the day of week upon which to fire
  363        * @param hour the hour (0-23) upon which to fire
  364        * @param minute the minute (0-59) upon which to fire
  365        * @return the newly created trigger
  366        */
  367       public static Trigger makeMonthlyTrigger(
  368               String trigName, int dayOfMonth, int hour, int minute) {
  369           Trigger trig = makeMonthlyTrigger(dayOfMonth, hour, minute);
  370           trig.setName(trigName);
  371           return trig;
  372       }
  373       
  374       /*
  375        * <p> Make a trigger that will fire every N days at the given time. </p>
  376        * 
  377        * <p> TThe generated trigger will not have its name, group,
  378        * start-time and end-time set. </p>
  379        * 
  380        * @param hour the hour (0-23) upon which to fire @param minute the minute
  381        * (0-59) upon which to fire @param interval the number of days between
  382        * firings public static Trigger makeDailyTrigger(int interval, int hour,
  383        * int minute) {
  384        * 
  385        * SimpleTrigger trig = new SimpleTrigger();
  386        * 
  387        * MILLISECONDS_IN_DAY);
  388        * trig.setRepeatCount(SimpleTrigger.REPEAT_INDEFINITELY);
  389        * 
  390        * return trig;
  391        *  }
  392        */
  393   
  394       /**
  395        * <p>
  396        * Make a trigger that will fire <code>repeatCount</code> times, waiting
  397        * <code>repeatInterval</code> milliseconds between each fire.
  398        * </p>
  399        * 
  400        * <p>
  401        * The generated trigger will not have its name, group,
  402        * or end-time set.  The Start time defaults to 'now'.
  403        * </p>
  404        *  
  405        * @param repeatCount the number of times to fire the trigger
  406        * @param repeatInterval the number of milliseconds to wait between fires
  407        * @return the newly created trigger
  408        */
  409       public static Trigger makeImmediateTrigger(
  410               int repeatCount, long repeatInterval) {
  411           SimpleTrigger trig = new SimpleTrigger();
  412           trig.setStartTime( new Date() );
  413           trig.setRepeatCount(repeatCount);
  414           trig.setRepeatInterval(repeatInterval);
  415           return trig;
  416       }    
  417       
  418       /**
  419        * <p>
  420        * Make a trigger that will fire <code>repeatCount</code> times, waiting
  421        * <code>repeatInterval</code> milliseconds between each fire.
  422        * </p>
  423        * 
  424        * <p>
  425        * The generated trigger will not have its name, group,
  426        * or end-time set.  The Start time defaults to 'now'.
  427        * </p>
  428        *
  429        * @param trigName the trigger's name 
  430        * @param repeatCount the number of times to fire the trigger
  431        * @param repeatInterval the number of milliseconds to wait between fires
  432        * @return the new trigger
  433        */
  434       public static Trigger makeImmediateTrigger(
  435               String trigName, int repeatCount, long repeatInterval) {
  436           Trigger trig = makeImmediateTrigger(repeatCount, repeatInterval);
  437           trig.setName(trigName);
  438           return trig;
  439       }    
  440       
  441       /**
  442        * <p>
  443        * Make a trigger that will fire every second, indefinitely.
  444        * </p>
  445        * 
  446        * <p>
  447        * The generated trigger will not have its name, group,
  448        * or end-time set.  The Start time defaults to 'now'.
  449        * </p>
  450        * @return the new trigger
  451        */
  452       public static Trigger makeSecondlyTrigger() {
  453           return makeSecondlyTrigger(1, SimpleTrigger.REPEAT_INDEFINITELY);
  454       }
  455   
  456       /**
  457        * <p>
  458        * Make a trigger that will fire every second, indefinitely.
  459        * </p>
  460        * 
  461        * <p>
  462        * The generated trigger will not have its group,
  463        * or end-time set.  The Start time defaults to 'now'.
  464        * </p>
  465        * 
  466        * @param trigName the trigger's name
  467        * @return the new trigger
  468        */
  469       public static Trigger makeSecondlyTrigger(String trigName) {
  470           return makeSecondlyTrigger(
  471                   trigName, 1, SimpleTrigger.REPEAT_INDEFINITELY);
  472       }
  473   
  474       
  475       /**
  476        * <p>
  477        * Make a trigger that will fire every N seconds, indefinitely.
  478        * </p>
  479        * 
  480        * <p>
  481        * The generated trigger will not have its name, group,
  482        * or end-time set.  The Start time defaults to 'now'.
  483        * </p>
  484        * 
  485        * @param intervalInSeconds the number of seconds between firings
  486        * @return the new trigger
  487        */
  488       public static Trigger makeSecondlyTrigger(int intervalInSeconds) {
  489           return makeSecondlyTrigger(
  490                   intervalInSeconds, SimpleTrigger.REPEAT_INDEFINITELY);
  491       }
  492   
  493       /**
  494        * <p>
  495        * Make a trigger that will fire every N seconds, with the given number of
  496        * repeats.
  497        * </p>
  498        * 
  499        * <p>
  500        * The generated trigger will not have its name, group,
  501        * or end-time set.  The Start time defaults to 'now'.
  502        * </p>
  503        * 
  504        * @param intervalInSeconds the number of seconds between firings
  505        * @param repeatCount the number of times to repeat the firing
  506        * @return the new trigger
  507        */
  508       public static Trigger makeSecondlyTrigger(
  509               int intervalInSeconds, int repeatCount) {
  510           SimpleTrigger trig = new SimpleTrigger();
  511   
  512           trig.setRepeatInterval(intervalInSeconds * 1000l);
  513           trig.setRepeatCount(repeatCount);
  514           trig.setStartTime(new Date()); 
  515           
  516           return trig;
  517       }
  518   
  519       /**
  520        * <p>
  521        * Make a trigger that will fire every N seconds, with the given number of
  522        * repeats.
  523        * </p>
  524        * 
  525        * <p>
  526        * The generated trigger will not have its group,
  527        * or end-time set.  The Start time defaults to 'now'.
  528        * </p>
  529        * 
  530        * @param trigName the trigger's name
  531        * @param intervalInSeconds the number of seconds between firings
  532        * @param repeatCount the number of times to repeat the firing
  533        * @return the new trigger
  534        */
  535       public static Trigger makeSecondlyTrigger(
  536               String trigName, int intervalInSeconds, int repeatCount) {
  537           Trigger trig = makeSecondlyTrigger(intervalInSeconds, repeatCount);
  538           trig.setName(trigName);
  539           return trig;
  540       }
  541   
  542       /**
  543        * <p>
  544        * Make a trigger that will fire every minute, indefinitely.
  545        * </p>
  546        * 
  547        * <p>
  548        * The generated trigger will not have its name, group,
  549        * or end-time set.  The Start time defaults to 'now'.
  550        * </p>
  551        *  
  552        * @return the new trigger
  553        */
  554       public static Trigger makeMinutelyTrigger() {
  555           return makeMinutelyTrigger(1, SimpleTrigger.REPEAT_INDEFINITELY);
  556       }
  557   
  558       /**
  559        * <p>
  560        * Make a trigger that will fire every minute, indefinitely.
  561        * </p>
  562        * 
  563        * <p>
  564        * The generated trigger will not have its group,
  565        * or end-time set.  The Start time defaults to 'now'.
  566        * </p>
  567        * 
  568        * @param trigName the trigger's name 
  569        * @return the new trigger
  570        */
  571       public static Trigger makeMinutelyTrigger(String trigName) {
  572           return makeMinutelyTrigger(
  573                   trigName, 1, SimpleTrigger.REPEAT_INDEFINITELY);
  574       }
  575       
  576       /**
  577        * <p>
  578        * Make a trigger that will fire every N minutes, indefinitely.
  579        * </p>
  580        * 
  581        * <p>
  582        * The generated trigger will not have its name, group,
  583        * or end-time set.  The Start time defaults to 'now'.
  584        * </p>
  585        * 
  586        * @param intervalInMinutes the number of minutes between firings
  587        * @return the new trigger
  588        */
  589       public static Trigger makeMinutelyTrigger(int intervalInMinutes) {
  590           return makeMinutelyTrigger(
  591                   intervalInMinutes, SimpleTrigger.REPEAT_INDEFINITELY);
  592       }
  593   
  594       /**
  595        * <p>
  596        * Make a trigger that will fire every N minutes, with the given number of
  597        * repeats.
  598        * </p>
  599        * 
  600        * <p>
  601        * The generated trigger will not have its name, group,
  602        * or end-time set.  The Start time defaults to 'now'.
  603        * </p>
  604        * 
  605        * @param intervalInMinutes the number of minutes between firings
  606        * @param repeatCount the number of times to repeat the firing
  607        * @return the new trigger
  608        */
  609       public static Trigger makeMinutelyTrigger(
  610               int intervalInMinutes, int repeatCount) {
  611           SimpleTrigger trig = new SimpleTrigger();
  612   
  613           trig.setRepeatInterval(intervalInMinutes * MILLISECONDS_IN_MINUTE);
  614           trig.setRepeatCount(repeatCount);
  615   
  616           trig.setStartTime(new Date());
  617           
  618           return trig;
  619       }
  620   
  621       /**
  622        * <p>
  623        * Make a trigger that will fire every N minutes, with the given number of
  624        * repeats.
  625        * </p>
  626        * 
  627        * <p>
  628        * The generated trigger will not have its group,
  629        * or end-time set.  The Start time defaults to 'now'.
  630        * </p>
  631        * 
  632        * @param trigName the trigger's name
  633        * @param intervalInMinutes the number of minutes between firings
  634        * @param repeatCount the number of times to repeat the firing
  635        * @return the new trigger
  636        */
  637       public static Trigger makeMinutelyTrigger(
  638               String trigName, int intervalInMinutes, int repeatCount) {
  639           Trigger trig = makeMinutelyTrigger(intervalInMinutes, repeatCount);
  640           trig.setName(trigName);
  641           return trig;
  642       }
  643   
  644       /**
  645        * <p>
  646        * Make a trigger that will fire every hour, indefinitely.
  647        * </p>
  648        * 
  649        * <p>
  650        * The generated trigger will not have its name, group,
  651        * or end-time set.  The Start time defaults to 'now'.
  652        * </p>
  653        *  
  654        * @return the new trigger
  655        */
  656       public static Trigger makeHourlyTrigger() {
  657           return makeHourlyTrigger(1, SimpleTrigger.REPEAT_INDEFINITELY);
  658       }
  659   
  660       /**
  661        * <p>
  662        * Make a trigger that will fire every hour, indefinitely.
  663        * </p>
  664        * 
  665        * <p>
  666        * The generated trigger will not have its group,
  667        * or end-time set.  The Start time defaults to 'now'.
  668        * </p>
  669        * 
  670        * @param trigName the trigger's name
  671        * @return the new trigger
  672        */
  673       public static Trigger makeHourlyTrigger(String trigName) {
  674           return makeHourlyTrigger(
  675                   trigName, 1, SimpleTrigger.REPEAT_INDEFINITELY);
  676       }
  677   
  678       /**
  679        * <p>
  680        * Make a trigger that will fire every N hours, indefinitely.
  681        * </p>
  682        * 
  683        * <p>
  684        * The generated trigger will not have its name, group,
  685        * or end-time set.  The Start time defaults to 'now'.
  686        * </p>
  687        * 
  688        * @param intervalInHours the number of hours between firings
  689        * @return the new trigger
  690        */
  691       public static Trigger makeHourlyTrigger(int intervalInHours) {
  692           return makeHourlyTrigger(
  693                   intervalInHours, SimpleTrigger.REPEAT_INDEFINITELY);
  694       }
  695   
  696       /**
  697        * <p>
  698        * Make a trigger that will fire every N hours, with the given number of
  699        * repeats.
  700        * </p>
  701        * 
  702        * <p>
  703        * The generated trigger will not have its name, group,
  704        * or end-time set.  The Start time defaults to 'now'.
  705        * </p>
  706        * 
  707        * @param intervalInHours the number of hours between firings
  708        * @param repeatCount the number of times to repeat the firing
  709        * @return the new trigger
  710        */
  711       public static Trigger makeHourlyTrigger(
  712               int intervalInHours, int repeatCount) {
  713           SimpleTrigger trig = new SimpleTrigger();
  714   
  715           trig.setRepeatInterval(intervalInHours * MILLISECONDS_IN_HOUR);
  716           trig.setRepeatCount(repeatCount);
  717   
  718           trig.setStartTime(new Date());
  719           
  720           return trig;
  721       }
  722   
  723       /**
  724        * <p>
  725        * Make a trigger that will fire every N hours, with the given number of
  726        * repeats.
  727        * </p>
  728        * 
  729        * <p>
  730        * The generated trigger will not have its group,
  731        * or end-time set.  The Start time defaults to 'now'.
  732        * </p>
  733        * 
  734        * @param trigName the trigger's name
  735        * @param intervalInHours the number of hours between firings
  736        * @param repeatCount the number of times to repeat the firing
  737        * @return the new trigger
  738        */
  739       public static Trigger makeHourlyTrigger(
  740               String trigName, int intervalInHours, int repeatCount) {
  741           Trigger trig =makeHourlyTrigger(intervalInHours, repeatCount);
  742           trig.setName(trigName);
  743           return trig;
  744       }
  745   
  746       /**
  747        * <p>
  748        * Returns a date that is rounded to the next even hour above the given
  749        * date.
  750        * </p>
  751        * 
  752        * <p>
  753        * For example an input date with a time of 08:13:54 would result in a date
  754        * with the time of 09:00:00. If the date's time is in the 23rd hour, the
  755        * date's 'day' will be promoted, and the time will be set to 00:00:00.
  756        * </p>
  757        * 
  758        * @param date
  759        *          the Date to round, if <code>null</code> the current time will
  760        *          be used
  761        * @return the new rounded date
  762        */
  763       public static Date getEvenHourDate(Date date) {
  764           if (date == null) {
  765               date = new Date();
  766           }
  767   
  768           Calendar c = Calendar.getInstance();
  769           c.setTime(date);
  770           c.setLenient(true);
  771   
  772           c.set(Calendar.HOUR_OF_DAY, c.get(Calendar.HOUR_OF_DAY) + 1);
  773           c.set(Calendar.MINUTE, 0);
  774           c.set(Calendar.SECOND, 0);
  775           c.set(Calendar.MILLISECOND, 0);
  776   
  777           return c.getTime();
  778       }
  779   
  780       /**
  781        * <p>
  782        * Returns a date that is rounded to the previous even hour below the given
  783        * date.
  784        * </p>
  785        * 
  786        * <p>
  787        * For example an input date with a time of 08:13:54 would result in a date
  788        * with the time of 08:00:00.
  789        * </p>
  790        * 
  791        * @param date
  792        *          the Date to round, if <code>null</code> the current time will
  793        *          be used
  794        * @return the new rounded date
  795        */
  796       public static Date getEvenHourDateBefore(Date date) {
  797           if (date == null) {
  798               date = new Date();
  799           }
  800   
  801           Calendar c = Calendar.getInstance();
  802           c.setTime(date);
  803   
  804           c.set(Calendar.MINUTE, 0);
  805           c.set(Calendar.SECOND, 0);
  806           c.set(Calendar.MILLISECOND, 0);
  807   
  808           return c.getTime();
  809       }
  810   
  811       /**
  812        * <p>
  813        * Returns a date that is rounded to the next even minute above the given
  814        * date.
  815        * </p>
  816        * 
  817        * <p>
  818        * For example an input date with a time of 08:13:54 would result in a date
  819        * with the time of 08:14:00. If the date's time is in the 59th minute,
  820        * then the hour (and possibly the day) will be promoted.
  821        * </p>
  822        * 
  823        * @param date
  824        *          the Date to round, if <code>null</code> the current time will
  825        *          be used
  826        * @return the new rounded date
  827        */
  828       public static Date getEvenMinuteDate(Date date) {
  829           if (date == null) {
  830               date = new Date();
  831           }
  832   
  833           Calendar c = Calendar.getInstance();
  834           c.setTime(date);
  835           c.setLenient(true);
  836   
  837           c.set(Calendar.MINUTE, c.get(Calendar.MINUTE) + 1);
  838           c.set(Calendar.SECOND, 0);
  839           c.set(Calendar.MILLISECOND, 0);
  840   
  841           return c.getTime();
  842       }
  843   
  844       /**
  845        * <p>
  846        * Returns a date that is rounded to the previous even minute below the 
  847        * given date.
  848        * </p>
  849        * 
  850        * <p>
  851        * For example an input date with a time of 08:13:54 would result in a date
  852        * with the time of 08:13:00.
  853        * </p>
  854        * 
  855        * @param date
  856        *          the Date to round, if <code>null</code> the current time will
  857        *          be used
  858        * @return the new rounded date
  859        */
  860       public static Date getEvenMinuteDateBefore(Date date) {
  861           if (date == null) {
  862               date = new Date();
  863           }
  864   
  865           Calendar c = Calendar.getInstance();
  866           c.setTime(date);
  867   
  868           c.set(Calendar.SECOND, 0);
  869           c.set(Calendar.MILLISECOND, 0);
  870   
  871           return c.getTime();
  872       }
  873   
  874       /**
  875        * <p>
  876        * Returns a date that is rounded to the next even second above the given
  877        * date.
  878        * </p>
  879        * 
  880        * @param date
  881        *          the Date to round, if <code>null</code> the current time will
  882        *          be used
  883        * @return the new rounded date
  884        */
  885       public static Date getEvenSecondDate(Date date) {
  886           if (date == null) {
  887               date = new Date();
  888           }
  889   
  890           Calendar c = Calendar.getInstance();
  891           c.setTime(date);
  892           c.setLenient(true);
  893   
  894           c.set(Calendar.SECOND, c.get(Calendar.SECOND) + 1);
  895           c.set(Calendar.MILLISECOND, 0);
  896   
  897           return c.getTime();
  898       }
  899   
  900       /**
  901        * <p>
  902        * Returns a date that is rounded to the previous even second below the
  903        * given date.
  904        * </p>
  905        * 
  906        * <p>
  907        * For example an input date with a time of 08:13:54.341 would result in a
  908        * date with the time of 08:13:00.000.
  909        * </p>
  910        * 
  911        * @param date
  912        *          the Date to round, if <code>null</code> the current time will
  913        *          be used
  914        * @return the new rounded date
  915        */
  916       public static Date getEvenSecondDateBefore(Date date) {
  917           if (date == null) {
  918               date = new Date();
  919           }
  920   
  921           Calendar c = Calendar.getInstance();
  922           c.setTime(date);
  923   
  924           c.set(Calendar.MILLISECOND, 0);
  925   
  926           return c.getTime();
  927       }
  928   
  929       /**
  930        * <p>
  931        * Returns a date that is rounded to the next even multiple of the given
  932        * minute.
  933        * </p>
  934        * 
  935        * <p>
  936        * For example an input date with a time of 08:13:54, and an input
  937        * minute-base of 5 would result in a date with the time of 08:15:00. The
  938        * same input date with an input minute-base of 10 would result in a date
  939        * with the time of 08:20:00. But a date with the time 08:53:31 and an
  940        * input minute-base of 45 would result in 09:00:00, because the even-hour
  941        * is the next 'base' for 45-minute intervals.
  942        * </p>
  943        * 
  944        * <p>
  945        * More examples: <table>
  946        * <tr>
  947        * <th>Input Time</th>
  948        * <th>Minute-Base</th>
  949        * <th>Result Time</th>
  950        * </tr>
  951        * <tr>
  952        * <td>11:16:41</td>
  953        * <td>20</td>
  954        * <td>11:20:00</td>
  955        * </tr>
  956        * <tr>
  957        * <td>11:36:41</td>
  958        * <td>20</td>
  959        * <td>11:40:00</td>
  960        * </tr>
  961        * <tr>
  962        * <td>11:46:41</td>
  963        * <td>20</td>
  964        * <td>12:00:00</td>
  965        * </tr>
  966        * <tr>
  967        * <td>11:26:41</td>
  968        * <td>30</td>
  969        * <td>11:30:00</td>
  970        * </tr>
  971        * <tr>
  972        * <td>11:36:41</td>
  973        * <td>30</td>
  974        * <td>12:00:00</td>
  975        * </tr>
  976        * <td>11:16:41</td>
  977        * <td>17</td>
  978        * <td>11:17:00</td>
  979        * </tr>
  980        * </tr>
  981        * <td>11:17:41</td>
  982        * <td>17</td>
  983        * <td>11:34:00</td>
  984        * </tr>
  985        * </tr>
  986        * <td>11:52:41</td>
  987        * <td>17</td>
  988        * <td>12:00:00</td>
  989        * </tr>
  990        * </tr>
  991        * <td>11:52:41</td>
  992        * <td>5</td>
  993        * <td>11:55:00</td>
  994        * </tr>
  995        * </tr>
  996        * <td>11:57:41</td>
  997        * <td>5</td>
  998        * <td>12:00:00</td>
  999        * </tr>
 1000        * </tr>
 1001        * <td>11:17:41</td>
 1002        * <td>0</td>
 1003        * <td>12:00:00</td>
 1004        * </tr>
 1005        * </tr>
 1006        * <td>11:17:41</td>
 1007        * <td>1</td>
 1008        * <td>11:08:00</td>
 1009        * </tr>
 1010        * </table>
 1011        * </p>
 1012        * 
 1013        * @param date
 1014        *          the Date to round, if <code>null</code> the current time will
 1015        *          be used
 1016        * @param minuteBase
 1017        *          the base-minute to set the time on
 1018        * @return the new rounded date
 1019        * 
 1020        * @see #getNextGivenSecondDate(Date, int)
 1021        */
 1022       public static Date getNextGivenMinuteDate(Date date, int minuteBase) {
 1023           if (minuteBase < 0 || minuteBase > 59) {
 1024               throw new IllegalArgumentException(
 1025                       "minuteBase must be >=0 and <= 59");
 1026           }
 1027   
 1028           if (date == null) {
 1029               date = new Date();
 1030           }
 1031   
 1032           Calendar c = Calendar.getInstance();
 1033           c.setTime(date);
 1034           c.setLenient(true);
 1035   
 1036           if (minuteBase == 0) {
 1037               c.set(Calendar.HOUR_OF_DAY, c.get(Calendar.HOUR_OF_DAY) + 1);
 1038               c.set(Calendar.MINUTE, 0);
 1039               c.set(Calendar.SECOND, 0);
 1040               c.set(Calendar.MILLISECOND, 0);
 1041   
 1042               return c.getTime();
 1043           }
 1044   
 1045           int minute = c.get(Calendar.MINUTE);
 1046   
 1047           int arItr = minute / minuteBase;
 1048   
 1049           int nextMinuteOccurance = minuteBase * (arItr + 1);
 1050   
 1051           if (nextMinuteOccurance < 60) {
 1052               c.set(Calendar.MINUTE, nextMinuteOccurance);
 1053               c.set(Calendar.SECOND, 0);
 1054               c.set(Calendar.MILLISECOND, 0);
 1055   
 1056               return c.getTime();
 1057           } else {
 1058               c.set(Calendar.HOUR_OF_DAY, c.get(Calendar.HOUR_OF_DAY) + 1);
 1059               c.set(Calendar.MINUTE, 0);
 1060               c.set(Calendar.SECOND, 0);
 1061               c.set(Calendar.MILLISECOND, 0);
 1062   
 1063               return c.getTime();
 1064           }
 1065       }
 1066   
 1067       /**
 1068        * <p>
 1069        * Returns a date that is rounded to the next even multiple of the given
 1070        * minute.
 1071        * </p>
 1072        * 
 1073        * <p>
 1074        * The rules for calculating the second are the same as those for
 1075        * calculating the minute in the method 
 1076        * <code>getNextGivenMinuteDate(..)<code>.
 1077        * </p>
 1078        *
 1079        * @param date the Date to round, if <code>null</code> the current time will
 1080        * be used
 1081        * @param secondBase the base-second to set the time on
 1082        * @return the new rounded date
 1083        * 
 1084        * @see #getNextGivenMinuteDate(Date, int)
 1085        */
 1086       public static Date getNextGivenSecondDate(Date date, int secondBase) {
 1087           if (secondBase < 0 || secondBase > 59) {
 1088               throw new IllegalArgumentException(
 1089                       "secondBase must be >=0 and <= 59");
 1090           }
 1091   
 1092           if (date == null) {
 1093               date = new Date();
 1094           }
 1095   
 1096           Calendar c = Calendar.getInstance();
 1097           c.setTime(date);
 1098           c.setLenient(true);
 1099   
 1100           if (secondBase == 0) {
 1101               c.set(Calendar.MINUTE, c.get(Calendar.MINUTE) + 1);
 1102               c.set(Calendar.SECOND, 0);
 1103               c.set(Calendar.MILLISECOND, 0);
 1104   
 1105               return c.getTime();
 1106           }
 1107   
 1108           int second = c.get(Calendar.SECOND);
 1109   
 1110           int arItr = second / secondBase;
 1111   
 1112           int nextSecondOccurance = secondBase * (arItr + 1);
 1113   
 1114           if (nextSecondOccurance < 60) {
 1115               c.set(Calendar.SECOND, nextSecondOccurance);
 1116               c.set(Calendar.MILLISECOND, 0);
 1117   
 1118               return c.getTime();
 1119           } else {
 1120               c.set(Calendar.MINUTE, c.get(Calendar.MINUTE) + 1);
 1121               c.set(Calendar.SECOND, 0);
 1122               c.set(Calendar.MILLISECOND, 0);
 1123   
 1124               return c.getTime();
 1125           }
 1126       }
 1127   
 1128       /**
 1129        * <p>
 1130        * Get a <code>Date</code> object that represents the given time, on
 1131        * today's date.
 1132        * </p>
 1133        * 
 1134        * @param second
 1135        *          The value (0-59) to give the seconds field of the date
 1136        * @param minute
 1137        *          The value (0-59) to give the minutes field of the date
 1138        * @param hour
 1139        *          The value (0-23) to give the hours field of the date
 1140        * @return the new date
 1141        */
 1142       public static Date getDateOf(int second, int minute, int hour) {
 1143           validateSecond(second);
 1144           validateMinute(minute);
 1145           validateHour(hour);
 1146   
 1147           Date date = new Date();
 1148   
 1149           Calendar c = Calendar.getInstance();
 1150           c.setTime(date);
 1151           c.setLenient(true);
 1152   
 1153           c.set(Calendar.HOUR_OF_DAY, hour);
 1154           c.set(Calendar.MINUTE, minute);
 1155           c.set(Calendar.SECOND, second);
 1156           c.set(Calendar.MILLISECOND, 0);
 1157   
 1158           return c.getTime();
 1159       }
 1160   
 1161       /**
 1162        * <p>
 1163        * Get a <code>Date</code> object that represents the given time, on the
 1164        * given date.
 1165        * </p>
 1166        * 
 1167        * @param second
 1168        *          The value (0-59) to give the seconds field of the date
 1169        * @param minute
 1170        *          The value (0-59) to give the minutes field of the date
 1171        * @param hour
 1172        *          The value (0-23) to give the hours field of the date
 1173        * @param dayOfMonth
 1174        *          The value (1-31) to give the day of month field of the date
 1175        * @param month
 1176        *          The value (1-12) to give the month field of the date
 1177        * @return the new date
 1178        */
 1179       public static Date getDateOf(int second, int minute, int hour,
 1180               int dayOfMonth, int month) {
 1181           validateSecond(second);
 1182           validateMinute(minute);
 1183           validateHour(hour);
 1184           validateDayOfMonth(dayOfMonth);
 1185           validateMonth(month);
 1186   
 1187           Date date = new Date();
 1188   
 1189           Calendar c = Calendar.getInstance();
 1190           c.setTime(date);
 1191   
 1192           c.set(Calendar.MONTH, month - 1);
 1193           c.set(Calendar.DAY_OF_MONTH, dayOfMonth);
 1194           c.set(Calendar.HOUR_OF_DAY, hour);
 1195           c.set(Calendar.MINUTE, minute);
 1196           c.set(Calendar.SECOND, second);
 1197           c.set(Calendar.MILLISECOND, 0);
 1198   
 1199           return c.getTime();
 1200       }
 1201   
 1202       /**
 1203        * <p>
 1204        * Get a <code>Date</code> object that represents the given time, on the
 1205        * given date.
 1206        * </p>
 1207        * 
 1208        * @param second
 1209        *          The value (0-59) to give the seconds field of the date
 1210        * @param minute
 1211        *          The value (0-59) to give the minutes field of the date
 1212        * @param hour
 1213        *          The value (0-23) to give the hours field of the date
 1214        * @param dayOfMonth
 1215        *          The value (1-31) to give the day of month field of the date
 1216        * @param month
 1217        *          The value (1-12) to give the month field of the date
 1218        * @param year
 1219        *          The value (1970-2099) to give the year field of the date
 1220        * @return the new date
 1221        */
 1222       public static Date getDateOf(int second, int minute, int hour,
 1223               int dayOfMonth, int month, int year) {
 1224           validateSecond(second);
 1225           validateMinute(minute);
 1226           validateHour(hour);
 1227           validateDayOfMonth(dayOfMonth);
 1228           validateMonth(month);
 1229           validateYear(year);
 1230   
 1231           Date date = new Date();
 1232   
 1233           Calendar c = Calendar.getInstance();
 1234           c.setTime(date);
 1235   
 1236           c.set(Calendar.YEAR, year);
 1237           c.set(Calendar.MONTH, month - 1);
 1238           c.set(Calendar.DAY_OF_MONTH, dayOfMonth);
 1239           c.set(Calendar.HOUR_OF_DAY, hour);
 1240           c.set(Calendar.MINUTE, minute);
 1241           c.set(Calendar.SECOND, second);
 1242           c.set(Calendar.MILLISECOND, 0);
 1243   
 1244           return c.getTime();
 1245       }
 1246   
 1247       /**
 1248        * Returns a list of Dates that are the next fire times of a 
 1249        * <code>Trigger</code>.
 1250        * The input trigger will be cloned before any work is done, so you need
 1251        * not worry about its state being altered by this method.
 1252        * 
 1253        * @param trigg
 1254        *          The trigger upon which to do the work
 1255        * @param cal
 1256        *          The calendar to apply to the trigger's schedule
 1257        * @param numTimes
 1258        *          The number of next fire times to produce
 1259        * @return List of java.util.Date objects
 1260        */
 1261       public static List computeFireTimes(Trigger trigg, org.quartz.Calendar cal,
 1262               int numTimes) {
 1263           LinkedList lst = new LinkedList();
 1264   
 1265           Trigger t = (Trigger) trigg.clone();
 1266   
 1267           if (t.getNextFireTime() == null) {
 1268               t.computeFirstFireTime(cal);
 1269           }
 1270   
 1271           for (int i = 0; i < numTimes; i++) {
 1272               Date d = t.getNextFireTime();
 1273               if (d != null) {
 1274                   lst.add(d);
 1275                   t.triggered(cal);
 1276               } else {
 1277                   break;
 1278               }
 1279           }
 1280   
 1281           return java.util.Collections.unmodifiableList(lst);
 1282       }
 1283   
 1284       /**
 1285        * Returns a list of Dates that are the next fire times of a 
 1286        * <code>Trigger</code>
 1287        * that fall within the given date range. The input trigger will be cloned
 1288        * before any work is done, so you need not worry about its state being
 1289        * altered by this method.
 1290        * 
 1291        * <p>
 1292        * NOTE: if this is a trigger that has previously fired within the given
 1293        * date range, then firings which have already occured will not be listed
 1294        * in the output List.
 1295        * </p>
 1296        * 
 1297        * @param trigg
 1298        *          The trigger upon which to do the work
 1299        * @param cal
 1300        *          The calendar to apply to the trigger's schedule
 1301        * @param from
 1302        *          The starting date at which to find fire times
 1303        * @param to
 1304        *          The ending date at which to stop finding fire times
 1305        * @return List of java.util.Date objects
 1306        */
 1307       public static List computeFireTimesBetween(Trigger trigg,
 1308               org.quartz.Calendar cal, Date from, Date to) {
 1309           LinkedList lst = new LinkedList();
 1310   
 1311           Trigger t = (Trigger) trigg.clone();
 1312   
 1313           if (t.getNextFireTime() == null) {
 1314               t.setStartTime(from);
 1315               t.setEndTime(to);
 1316               t.computeFirstFireTime(cal);
 1317           }
 1318   
 1319           // TODO: this method could be more efficient by using logic specific
 1320           //        to the type of trigger ...
 1321           while (true) {
 1322               Date d = t.getNextFireTime();
 1323               if (d != null) {
 1324                   if (d.before(from)) {
 1325                       t.triggered(cal);
 1326                       continue;
 1327                   }
 1328                   if (d.after(to)) {
 1329                       break;
 1330                   }
 1331                   lst.add(d);
 1332                   t.triggered(cal);
 1333               } else {
 1334                   break;
 1335               }
 1336           }
 1337   
 1338           return java.util.Collections.unmodifiableList(lst);
 1339       }
 1340   
 1341       /**
 1342        * Translate a date & time from a users timezone to the another
 1343        * (probably server) timezone to assist in creating a simple trigger with 
 1344        * the right date & time.
 1345        * 
 1346        * @param date the date to translate
 1347        * @param src the original time-zone
 1348        * @param dest the destination time-zone
 1349        * @return the translated date
 1350        */
 1351       public static Date translateTime(Date date, TimeZone src, TimeZone dest) {
 1352   
 1353           Date newDate = new Date();
 1354   
 1355           int offset = (
 1356                   getOffset(date.getTime(), dest) - getOffset(date.getTime(), src));
 1357   
 1358           newDate.setTime(date.getTime() - offset);
 1359   
 1360           return newDate;
 1361       }
 1362       
 1363       /**
 1364        * Gets the offset from UT for the given date in the given timezone, 
 1365        * taking into account daylight savings.
 1366        * 
 1367        * <p>
 1368        * Equivalent of TimeZone.getOffset(date) in JDK 1.4, but Quartz is trying
 1369        * to support JDK 1.3.
 1370        * </p>
 1371        * 
 1372        * @param date the date (in milliseconds) that is the base for the offset
 1373        * @param tz the time-zone to calculate to offset to
 1374        * @return the offset
 1375        */
 1376       public static int getOffset(long date, TimeZone tz) {
 1377           
 1378           if (tz.inDaylightTime(new Date(date))) {
 1379               return tz.getRawOffset() + getDSTSavings(tz);
 1380           }
 1381           
 1382           return tz.getRawOffset();
 1383       }
 1384   
 1385       /**
 1386        * <p>
 1387        * Equivalent of TimeZone.getDSTSavings() in JDK 1.4, but Quartz is trying
 1388        * to support JDK 1.3.
 1389        * </p>
 1390        * 
 1391        * @param tz the target time-zone
 1392        * @return the amount of saving time in milliseconds
 1393        */
 1394       public static int getDSTSavings(TimeZone tz) {
 1395           
 1396           if (tz.useDaylightTime()) {
 1397               return 3600000;
 1398           }
 1399           return 0;
 1400       }
 1401   }

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