Java > Open Source Codes > org > quartz > impl > calendar > DailyCalendar


1 package org.quartz.impl.calendar;
2
3 import java.text.NumberFormat ;
4 import java.util.ArrayList ;
5 import java.util.Calendar ;
6 import java.util.StringTokenizer ;
7 import java.util.TimeZone ;
8
9 /**
10  * This implementation of the Calendar excludes (or includes - see below) a
11  * specified time range each day. For example, you could use this calendar to
12  * exclude business hours (8AM - 5PM) every day. Each <CODE>DailyCalendar</CODE>
13  * only allows a single time range to be specified, and that time range may not
14  * cross daily boundaries (i.e. you cannot specify a time range from 8PM - 5AM).
15  * If the property <CODE>invertTimeRange</CODE> is <CODE>false</CODE> (default),
16  * the time range defines a range of times in which triggers are not allowed to
17  * fire. If <CODE>invertTimeRange</CODE> is <CODE>true</CODE>, the time range
18  * is inverted &ndash; that is, all times <I>outside</I> the defined time range
19  * are excluded.
20  * <P>
21  * Note when using <CODE>DailyCalendar</CODE>, it behaves on the same principals
22  * as, for example, {@link org.quartz.impl.calendar.WeeklyCalendar
23  * WeeklyCalendar}. <CODE>WeeklyCalendar</CODE> defines a set of days that are
24  * excluded <I>every week</I>. Likewise, <CODE>DailyCalendar</CODE> defines a
25  * set of times that are excluded <I>every day</I>.
26  *
27  * @author Mike Funk, Aaron Craven
28  */
29 public class DailyCalendar extends BaseCalendar {
30     static final long serialVersionUID = -7561220099904944039L;
31     
32     private static final String invalidHourOfDay = "Invalid hour of day: ";
33     private static final String invalidMinute = "Invalid minute: ";
34     private static final String invalidSecond = "Invalid second: ";
35     private static final String invalidMillis = "Invalid millis: ";
36     private static final String invalidTimeRange = "Invalid time range: ";
37     private static final String separator = " - ";
38     private static final long oneMillis = 1;
39     private static final String colon = ":";
40
41     /** @deprecated The use of <code>name</code> is no longer supported. */
42     private String name;
43     
44     private int rangeStartingHourOfDay;
45     private int rangeStartingMinute;
46     private int rangeStartingSecond;
47     private int rangeStartingMillis;
48     private int rangeEndingHourOfDay;
49     private int rangeEndingMinute;
50     private int rangeEndingSecond;
51     private int rangeEndingMillis;
52     
53     private boolean invertTimeRange = false;
54
55     /**
56      * Create a <CODE>DailyCalendar</CODE> with a time range defined by the
57      * specified strings and no <CODE>baseCalendar</CODE>.
58      * <CODE>rangeStartingTime</CODE> and <CODE>rangeEndingTime</CODE>
59      * must be in the format &quot;HH:MM[:SS[:mmm]]&quot; where:
60      * <UL><LI>HH is the hour of the specified time. The hour should be
61      * specified using military (24-hour) time and must be in the range
62      * 0 to 23.</LI>
63      * <LI>MM is the minute of the specified time and must be in the range
64      * 0 to 59.</LI>
65      * <LI>SS is the second of the specified time and must be in the range
66      * 0 to 59.</LI>
67      * <LI>mmm is the millisecond of the specified time and must be in the
68      * range 0 to 999.</LI>
69      * <LI>items enclosed in brackets ('[', ']') are optional.</LI>
70      * <LI>The time range starting time must be before the time range ending
71      * time. Note this means that a time range may not cross daily
72      * boundaries (10PM - 2AM)</LI>
73      * </UL>
74      *
75      * <p>
76      * <b>Note:</b> This <CODE>DailyCalendar</CODE> will use the
77      * <code>{@link TimeZone#getDefault()}</code> time zone unless an explicit
78      * time zone is set via <code>{@link BaseCalendar#setTimeZone(TimeZone)}</code>
79      * </p>
80      *
81      * @param rangeStartingTime a String representing the starting time for the
82      * time range
83      * @param rangeEndingTime a String representing the ending time for the
84      * the time range
85      */
86     public DailyCalendar(String rangeStartingTime,
87                          String rangeEndingTime) {
88         super();
89         setTimeRange(rangeStartingTime, rangeEndingTime);
90     }
91
92     /**
93      * Create a <CODE>DailyCalendar</CODE> with a time range defined by the
94      * specified strings and the specified <CODE>baseCalendar</CODE>.
95      * <CODE>rangeStartingTime</CODE> and <CODE>rangeEndingTime</CODE>
96      * must be in the format &quot;HH:MM[:SS[:mmm]]&quot; where:
97      * <UL><LI>HH is the hour of the specified time. The hour should be
98      * specified using military (24-hour) time and must be in the range
99      * 0 to 23.</LI>
100      * <LI>MM is the minute of the specified time and must be in the range
101      * 0 to 59.</LI>
102      * <LI>SS is the second of the specified time and must be in the range
103      * 0 to 59.</LI>
104      * <LI>mmm is the millisecond of the specified time and must be in the
105      * range 0 to 999.</LI>
106      * <LI>items enclosed in brackets ('[', ']') are optional.</LI>
107      * <LI>The time range starting time must be before the time range ending
108      * time. Note this means that a time range may not cross daily
109      * boundaries (10PM - 2AM)</LI>
110      * </UL>
111      *
112      * <p>
113      * <b>Note:</b> This <CODE>DailyCalendar</CODE> will use the
114      * <code>{@link TimeZone#getDefault()}</code> time zone unless an explicit
115      * time zone is set via <code>{@link BaseCalendar#setTimeZone(TimeZone)}</code>
116      * </p>
117      *
118      * @param baseCalendar the base calendar for this calendar instance
119      * &ndash; see {@link BaseCalendar} for more
120      * information on base calendar functionality
121      * @param rangeStartingTime a String representing the starting time for the
122      * time range
123      * @param rangeEndingTime a String representing the ending time for the
124      * time range
125      */
126     public DailyCalendar(org.quartz.Calendar baseCalendar,
127                          String rangeStartingTime,
128                          String rangeEndingTime) {
129         super(baseCalendar);
130         setTimeRange(rangeStartingTime, rangeEndingTime);
131     }
132
133     /**
134      * Create a <CODE>DailyCalendar</CODE> with a time range defined by the
135      * specified values and no <CODE>baseCalendar</CODE>. Values are subject to
136      * the following validations:
137      * <UL><LI>Hours must be in the range 0-23 and are expressed using military
138      * (24-hour) time.</LI>
139      * <LI>Minutes must be in the range 0-59</LI>
140      * <LI>Seconds must be in the range 0-59</LI>
141      * <LI>Milliseconds must be in the range 0-999</LI>
142      * <LI>The time range starting time must be before the time range ending
143      * time. Note this means that a time range may not cross daily
144      * boundaries (10PM - 2AM)</LI>
145      * </UL>
146      *
147      * <p>
148      * <b>Note:</b> This <CODE>DailyCalendar</CODE> will use the
149      * <code>{@link TimeZone#getDefault()}</code> time zone unless an explicit
150      * time zone is set via <code>{@link BaseCalendar#setTimeZone(TimeZone)}</code>
151      * </p>
152      *
153      * @param rangeStartingHourOfDay the hour of the start of the time range
154      * @param rangeStartingMinute the minute of the start of the time range
155      * @param rangeStartingSecond the second of the start of the time range
156      * @param rangeStartingMillis the millisecond of the start of the time
157      * range
158      * @param rangeEndingHourOfDay the hour of the end of the time range
159      * @param rangeEndingMinute the minute of the end of the time range
160      * @param rangeEndingSecond the second of the end of the time range
161      * @param rangeEndingMillis the millisecond of the start of the time
162      * range
163      */
164     public DailyCalendar(int rangeStartingHourOfDay,
165                          int rangeStartingMinute,
166                          int rangeStartingSecond,
167                          int rangeStartingMillis,
168                          int rangeEndingHourOfDay,
169                          int rangeEndingMinute,
170                          int rangeEndingSecond,
171                          int rangeEndingMillis) {
172         super();
173         setTimeRange(rangeStartingHourOfDay,
174                      rangeStartingMinute,
175                      rangeStartingSecond,
176                      rangeStartingMillis,
177                      rangeEndingHourOfDay,
178                      rangeEndingMinute,
179                      rangeEndingSecond,
180                      rangeEndingMillis);
181     }
182     
183     /**
184      * Create a <CODE>DailyCalendar</CODE> with a time range defined by the
185      * specified values and the specified <CODE>baseCalendar</CODE>. Values are
186      * subject to the following validations:
187      * <UL><LI>Hours must be in the range 0-23 and are expressed using military
188      * (24-hour) time.</LI>
189      * <LI>Minutes must be in the range 0-59</LI>
190      * <LI>Seconds must be in the range 0-59</LI>
191      * <LI>Milliseconds must be in the range 0-999</LI>
192      * <LI>The time range starting time must be before the time range ending
193      * time. Note this means that a time range may not cross daily
194      * boundaries (10PM - 2AM)</LI>
195      * </UL>
196      *
197      * <p>
198      * <b>Note:</b> This <CODE>DailyCalendar</CODE> will use the
199      * <code>{@link TimeZone#getDefault()}</code> time zone unless an explicit
200      * time zone is set via <code>{@link BaseCalendar#setTimeZone(TimeZone)}</code>
201      * </p>
202      *
203      * @param baseCalendar the base calendar for this calendar
204      * instance &ndash; see
205      * {@link BaseCalendar} for more
206      * information on base calendar
207      * functionality
208      * @param rangeStartingHourOfDay the hour of the start of the time range
209      * @param rangeStartingMinute the minute of the start of the time range
210      * @param rangeStartingSecond the second of the start of the time range
211      * @param rangeStartingMillis the millisecond of the start of the time
212      * range
213      * @param rangeEndingHourOfDay the hour of the end of the time range
214      * @param rangeEndingMinute the minute of the end of the time range
215      * @param rangeEndingSecond the second of the end of the time range
216      * @param rangeEndingMillis the millisecond of the start of the time
217      * range
218      */
219     public DailyCalendar(org.quartz.Calendar baseCalendar,
220                          int rangeStartingHourOfDay,
221                          int rangeStartingMinute,
222                          int rangeStartingSecond,
223                          int rangeStartingMillis,
224                          int rangeEndingHourOfDay,
225                          int rangeEndingMinute,
226                          int rangeEndingSecond,
227                          int rangeEndingMillis) {
228         super(baseCalendar);
229         setTimeRange(rangeStartingHourOfDay,
230                      rangeStartingMinute,
231                      rangeStartingSecond,
232                      rangeStartingMillis,
233                      rangeEndingHourOfDay,
234                      rangeEndingMinute,
235                      rangeEndingSecond,
236                      rangeEndingMillis);
237     }
238
239     /**
240      * Create a <CODE>DailyCalendar</CODE> with a time range defined by the
241      * specified <CODE>java.util.Calendar</CODE>s and no
242      * <CODE>baseCalendar</CODE>. The Calendars are subject to the following
243      * considerations:
244      * <UL><LI>Only the time-of-day fields of the specified Calendars will be
245      * used (the date fields will be ignored)</LI>
246      * <LI>The starting time must be before the ending time of the defined
247      * time range. Note this means that a time range may not cross
248      * daily boundaries (10PM - 2AM). <I>(because only time fields are
249      * are used, it is possible for two Calendars to represent a valid
250      * time range and
251      * <CODE>rangeStartingCalendar.after(rangeEndingCalendar) ==
252      * true</CODE>)</I></LI>
253      * </UL>
254      *
255      * <p>
256      * <b>Note:</b> This <CODE>DailyCalendar</CODE> will use the
257      * <code>{@link TimeZone#getDefault()}</code> time zone unless an explicit
258      * time zone is set via <code>{@link BaseCalendar#setTimeZone(TimeZone)}</code>
259      * </p>
260      *
261      * @param rangeStartingCalendar a java.util.Calendar representing the
262      * starting time for the time range
263      * @param rangeEndingCalendar a java.util.Calendar representing the ending
264      * time for the time range
265      */
266     public DailyCalendar(
267                          Calendar rangeStartingCalendar,
268                          Calendar rangeEndingCalendar) {
269         super();
270         setTimeRange(rangeStartingCalendar, rangeEndingCalendar);
271     }
272
273     /**
274      * Create a <CODE>DailyCalendar</CODE> with a time range defined by the
275      * specified <CODE>java.util.Calendar</CODE>s and the specified
276      * <CODE>baseCalendar</CODE>. The Calendars are subject to the following
277      * considerations:
278      * <UL><LI>Only the time-of-day fields of the specified Calendars will be
279      * used (the date fields will be ignored)</LI>
280      * <LI>The starting time must be before the ending time of the defined
281      * time range. Note this means that a time range may not cross
282      * daily boundaries (10PM - 2AM). <I>(because only time fields are
283      * are used, it is possible for two Calendars to represent a valid
284      * time range and
285      * <CODE>rangeStartingCalendar.after(rangeEndingCalendar) ==
286      * true</CODE>)</I></LI>
287      * </UL>
288      *
289      * <p>
290      * <b>Note:</b> This <CODE>DailyCalendar</CODE> will use the
291      * <code>{@link TimeZone#getDefault()}</code> time zone unless an explicit
292      * time zone is set via <code>{@link BaseCalendar#setTimeZone(TimeZone)}</code>
293      * </p>
294      *
295      * @param baseCalendar the base calendar for this calendar instance
296      * &ndash; see {@link BaseCalendar} for more
297      * information on base calendar functionality
298      * @param rangeStartingCalendar a java.util.Calendar representing the
299      * starting time for the time range
300      * @param rangeEndingCalendar a java.util.Calendar representing the ending
301      * time for the time range
302      */
303     public DailyCalendar(org.quartz.Calendar baseCalendar,
304                          Calendar rangeStartingCalendar,
305                          Calendar rangeEndingCalendar) {
306         super(baseCalendar);
307         setTimeRange(rangeStartingCalendar, rangeEndingCalendar);
308     }
309
310     /**
311      * Create a <CODE>DailyCalendar</CODE> with a time range defined by the
312      * specified values and no <CODE>baseCalendar</CODE>. The values are
313      * subject to the following considerations:
314      * <UL><LI>Only the time-of-day portion of the specified values will be
315      * used</LI>
316      * <LI>The starting time must be before the ending time of the defined
317      * time range. Note this means that a time range may not cross
318      * daily boundaries (10PM - 2AM). <I>(because only time value are
319      * are used, it is possible for the two values to represent a valid
320      * time range and <CODE>rangeStartingTime &gt;
321      * rangeEndingTime</CODE>)</I></LI>
322      * </UL>
323      *
324      * <p>
325      * <b>Note:</b> This <CODE>DailyCalendar</CODE> will use the
326      * <code>{@link TimeZone#getDefault()}</code> time zone unless an explicit
327      * time zone is set via <code>{@link BaseCalendar#setTimeZone(TimeZone)}</code>.
328      * You should use <code>{@link #DailyCalendar(String, TimeZone, long, long)}</code>
329      * if you don't want the given <code>rangeStartingTimeInMillis</code> and
330      * <code>rangeEndingTimeInMillis</code> to be evaluated in the default
331      * time zone.
332      * </p>
333      *
334      * @param rangeStartingTimeInMillis a long representing the starting time
335      * for the time range
336      * @param rangeEndingTimeInMillis a long representing the ending time for
337      * the time range
338      */
339     public DailyCalendar(long rangeStartingTimeInMillis,
340                          long rangeEndingTimeInMillis) {
341         super();
342         setTimeRange(rangeStartingTimeInMillis,
343                      rangeEndingTimeInMillis);
344     }
345
346     /**
347      * Create a <CODE>DailyCalendar</CODE> with a time range defined by the
348      * specified values and the specified <CODE>baseCalendar</CODE>. The values
349      * are subject to the following considerations:
350      * <UL><LI>Only the time-of-day portion of the specified values will be
351      * used</LI>
352      * <LI>The starting time must be before the ending time of the defined
353      * time range. Note this means that a time range may not cross
354      * daily boundaries (10PM - 2AM). <I>(because only time value are
355      * are used, it is possible for the two values to represent a valid
356      * time range and <CODE>rangeStartingTime &gt;
357      * rangeEndingTime</CODE>)</I></LI>
358      * </UL>
359      *
360      * <p>
361      * <b>Note:</b> This <CODE>DailyCalendar</CODE> will use the
362      * <code>{@link TimeZone#getDefault()}</code> time zone unless an explicit
363      * time zone is set via <code>{@link BaseCalendar#setTimeZone(TimeZone)}</code>.
364      * You should use <code>{@link #DailyCalendar(String, Calendar, TimeZone, long, long)}</code>
365      * if you don't want the given <code>rangeStartingTimeInMillis</code> and
366      * <code>rangeEndingTimeInMillis</code> to be evaluated in the default
367      * time zone.
368      * </p>
369      *
370      * @param baseCalendar the base calendar for this calendar
371      * instance &ndash; see {@link
372      * BaseCalendar} for more information on
373      * base calendar functionality
374      * @param rangeStartingTimeInMillis a long representing the starting time
375      * for the time range
376      * @param rangeEndingTimeInMillis a long representing the ending time for
377      * the time range
378      */
379     public DailyCalendar(org.quartz.Calendar baseCalendar,
380                          long rangeStartingTimeInMillis,
381                          long rangeEndingTimeInMillis) {
382         super(baseCalendar);
383         setTimeRange(rangeStartingTimeInMillis,
384                      rangeEndingTimeInMillis);
385     }
386     
387     /**
388      * Create a <CODE>DailyCalendar</CODE> with a time range defined by the
389      * specified values and no <CODE>baseCalendar</CODE>. The values are
390      * subject to the following considerations:
391      * <UL><LI>Only the time-of-day portion of the specified values will be
392      * used</LI>
393      * <LI>The starting time must be before the ending time of the defined
394      * time range. Note this means that a time range may not cross
395      * daily boundaries (10PM - 2AM). <I>(because only time value are
396      * are used, it is possible for the two values to represent a valid
397      * time range and <CODE>rangeStartingTime &gt;
398      * rangeEndingTime</CODE>)</I></LI>
399      * </UL>
400      *
401      * @param timeZone the time zone for of the
402      * <code>DailyCalendar</code> which will
403      * also be used to resolve the given
404      * start/end times.
405      * @param rangeStartingTimeInMillis a long representing the starting time
406      * for the time range
407      * @param rangeEndingTimeInMillis a long representing the ending time for
408      * the time range
409      */
410     public DailyCalendar(TimeZone timeZone,
411                          long rangeStartingTimeInMillis,
412                          long rangeEndingTimeInMillis) {
413         super(timeZone);
414         setTimeRange(rangeStartingTimeInMillis,
415                      rangeEndingTimeInMillis);
416     }
417
418     /**
419      * Create a <CODE>DailyCalendar</CODE> with a time range defined by the
420      * specified values and the specified <CODE>baseCalendar</CODE>. The values
421      * are subject to the following considerations:
422      * <UL><LI>Only the time-of-day portion of the specified values will be
423      * used</LI>
424      * <LI>The starting time must be before the ending time of the defined
425      * time range. Note this means that a time range may not cross
426      * daily boundaries (10PM - 2AM). <I>(because only time value are
427      * are used, it is possible for the two values to represent a valid
428      * time range and <CODE>rangeStartingTime &gt;
429      * rangeEndingTime</CODE>)</I></LI>
430      * </UL>
431      *
432      * @param baseCalendar the base calendar for this calendar
433      * instance &ndash; see {@link
434      * BaseCalendar} for more information on
435      * base calendar functionality
436      * @param timeZone the time zone for of the
437      * <code>DailyCalendar</code> which will
438      * also be used to resolve the given
439      * start/end times.
440      * @param rangeStartingTimeInMillis a long representing the starting time
441      * for the time range
442      * @param rangeEndingTimeInMillis a long representing the ending time for
443      * the time range
444      */
445     public DailyCalendar(org.quartz.Calendar baseCalendar,
446                          TimeZone timeZone,
447                          long rangeStartingTimeInMillis,
448                          long rangeEndingTimeInMillis) {
449         super(baseCalendar, timeZone);
450         setTimeRange(rangeStartingTimeInMillis,
451                      rangeEndingTimeInMillis);
452     }
453
454     /**
455      * @deprecated The use of <code>name</code> is no longer supported.
456      *
457      * @see DailyCalendar#DailyCalendar(String, String)
458      */
459     public DailyCalendar(String name,
460                          String rangeStartingTime,
461                          String rangeEndingTime) {
462         this(rangeStartingTime, rangeEndingTime);
463         this.name = name;
464     }
465     
466     /**
467      * @deprecated The use of <code>name</code> is no longer supported.
468      *
469      * @see DailyCalendar#DailyCalendar(org.quartz.Calendar, String, String)
470      */
471     public DailyCalendar(String name,
472                          org.quartz.Calendar baseCalendar,
473                          String rangeStartingTime,
474                          String rangeEndingTime) {
475         this(baseCalendar, rangeStartingTime, rangeEndingTime);
476         this.name = name;
477     }
478     
479     /**
480      * @deprecated The use of <code>name</code> is no longer supported.
481      *
482      * @see DailyCalendar#DailyCalendar(int, int, int, int, int, int, int, int)
483      */
484     public DailyCalendar(String name,
485                          int rangeStartingHourOfDay,
486                          int rangeStartingMinute,
487                          int rangeStartingSecond,
488                          int rangeStartingMillis,
489                          int rangeEndingHourOfDay,
490                          int rangeEndingMinute,
491                          int rangeEndingSecond,
492                          int rangeEndingMillis) {
493         this(rangeStartingHourOfDay,
494             rangeStartingMinute,
495             rangeStartingSecond,
496             rangeStartingMillis,
497             rangeEndingHourOfDay,
498             rangeEndingMinute,
499             rangeEndingSecond,
500             rangeEndingMillis);
501         this.name = name;
502     }
503     
504     /**
505      * @deprecated The use of <code>name</code> is no longer supported.
506      *
507      * @see DailyCalendar#DailyCalendar(org.quartz.Calendar, int, int, int, int, int, int, int, int)
508      */
509     public DailyCalendar(String name,
510                          org.quartz.Calendar baseCalendar,
511                          int rangeStartingHourOfDay,
512                          int rangeStartingMinute,
513                          int rangeStartingSecond,
514                          int rangeStartingMillis,
515                          int rangeEndingHourOfDay,
516                          int rangeEndingMinute,
517                          int rangeEndingSecond,
518                          int rangeEndingMillis) {
519         this(baseCalendar,
520             rangeStartingHourOfDay,
521             rangeStartingMinute,
522             rangeStartingSecond,
523             rangeStartingMillis,
524             rangeEndingHourOfDay,
525             rangeEndingMinute,
526             rangeEndingSecond,
527             rangeEndingMillis);
528         this.name = name;
529     }
530     
531     /**
532      * @deprecated The use of <code>name</code> is no longer supported.
533      *
534      * @see DailyCalendar#DailyCalendar(Calendar, Calendar)
535      */
536     public DailyCalendar(String name,
537                          Calendar rangeStartingCalendar,
538                          Calendar rangeEndingCalendar) {
539         this(rangeStartingCalendar, rangeEndingCalendar);
540         this.name = name;
541     }
542     
543     /**
544      * @deprecated The use of <code>name</code> is no longer supported.
545      *
546      * @see DailyCalendar#DailyCalendar(org.quartz.Calendar, Calendar, Calendar)
547      */
548     public DailyCalendar(String name,
549                          org.quartz.Calendar baseCalendar,
550                          Calendar rangeStartingCalendar,
551                          Calendar rangeEndingCalendar) {
552         this(baseCalendar, rangeStartingCalendar, rangeEndingCalendar);
553         this.name = name;
554     }
555     
556     /**
557      * @deprecated The use of <code>name</code> is no longer supported.
558      *
559      * @see DailyCalendar#DailyCalendar(long, long)
560      */
561     public DailyCalendar(String name,
562                          long rangeStartingTimeInMillis,
563                          long rangeEndingTimeInMillis) {
564         this(rangeStartingTimeInMillis, rangeEndingTimeInMillis);
565         this.name = name;
566     }
567     
568     /**
569      * @deprecated The use of <code>name</code> is no longer supported.
570      *
571      * @see DailyCalendar#DailyCalendar(org.quartz.Calendar, long, long)
572      */
573     public DailyCalendar(String name,
574                          org.quartz.Calendar baseCalendar,
575                          long rangeStartingTimeInMillis,
576                          long rangeEndingTimeInMillis) {
577         this(baseCalendar, rangeStartingTimeInMillis, rangeEndingTimeInMillis);
578         this.name = name;
579     }
580     
581     /**
582      * @deprecated The use of <code>name</code> is no longer supported.
583      *
584      * @see DailyCalendar#DailyCalendar(TimeZone, long, long)
585      */
586     public DailyCalendar(String name,
587                          TimeZone timeZone,
588                          long rangeStartingTimeInMillis,
589                          long rangeEndingTimeInMillis) {
590         this(timeZone,
591             rangeStartingTimeInMillis,
592             rangeEndingTimeInMillis);
593         this.name = name;
594     }
595     
596     /**
597      * @deprecated The use of <code>name</code> is no longer supported.
598      *
599      * @see DailyCalendar#DailyCalendar(org.quartz.Calendar, TimeZone, long, long)
600      */
601     public DailyCalendar(String name,
602                          org.quartz.Calendar baseCalendar,
603                          TimeZone timeZone,
604                          long rangeStartingTimeInMillis,
605                          long rangeEndingTimeInMillis) {
606         this(baseCalendar,
607             timeZone,
608             rangeStartingTimeInMillis,
609             rangeEndingTimeInMillis);
610         this.name = name;
611     }
612
613     /**
614      * Returns the name of the <CODE>DailyCalendar</CODE>
615      *
616      * @return the name of the <CODE>DailyCalendar</CODE>
617      *
618      * @deprecated The use of <code>name</code> is no longer supported.
619      */
620     public String getName() {
621         return name;
622     }
623
624     /**
625      * Determines whether the given time (in milliseconds) is 'included' by the
626      * <CODE>BaseCalendar</CODE>
627      *
628      * @param timeInMillis the date/time to test
629      * @return a boolean indicating whether the specified time is 'included' by
630      * the <CODE>BaseCalendar</CODE>
631      */
632     public boolean isTimeIncluded(long timeInMillis) {
633         if ((getBaseCalendar() != null) &&
634                 (getBaseCalendar().isTimeIncluded(timeInMillis) == false)) {
635             return false;
636         }
637         
638         long startOfDayInMillis = getStartOfDayJavaCalendar(timeInMillis).getTime().getTime();
639         long endOfDayInMillis = getEndOfDayJavaCalendar(timeInMillis).getTime().getTime();
640         long timeRangeStartingTimeInMillis =
641             getTimeRangeStartingTimeInMillis(timeInMillis);
642         long timeRangeEndingTimeInMillis =
643             getTimeRangeEndingTimeInMillis(timeInMillis);
644         if (!invertTimeRange) {
645             return
646                 ((timeInMillis > startOfDayInMillis &&
647                     timeInMillis < timeRangeStartingTimeInMillis) ||
648                 (timeInMillis > timeRangeEndingTimeInMillis &&
649                     timeInMillis < endOfDayInMillis));
650         } else {
651             return ((timeInMillis >= timeRangeStartingTimeInMillis) &&
652                     (timeInMillis <= timeRangeEndingTimeInMillis));
653         }
654     }
655
656     /**
657      * Determines the next time included by the <CODE>DailyCalendar</CODE>
658      * after the specified time.
659      *
660      * @param timeInMillis the initial date/time after which to find an
661      * included time
662      * @return the time in milliseconds representing the next time included
663      * after the specified time.
664      */
665     public long getNextIncludedTime(long timeInMillis) {
666         long nextIncludedTime = timeInMillis + oneMillis;
667         
668         while (!isTimeIncluded(nextIncludedTime)) {
669             if (!invertTimeRange) {
670                 //If the time is in a range excluded by this calendar, we can
671 // move to the end of the excluded time range and continue
672 // testing from there. Otherwise, if nextIncludedTime is
673 // excluded by the baseCalendar, ask it the next time it
674 // includes and begin testing from there. Failing this, add one
675 // millisecond and continue testing.
676 if ((nextIncludedTime >=
677                         getTimeRangeStartingTimeInMillis(nextIncludedTime)) &&
678                     (nextIncludedTime <=
679                         getTimeRangeEndingTimeInMillis(nextIncludedTime))) {
680                     
681                     nextIncludedTime =
682                         getTimeRangeEndingTimeInMillis(nextIncludedTime) +
683                             oneMillis;
684                 } else if ((getBaseCalendar() != null) &&
685                         (!getBaseCalendar().isTimeIncluded(nextIncludedTime))){
686                     nextIncludedTime =
687                         getBaseCalendar().getNextIncludedTime(nextIncludedTime);
688                 } else {
689                     nextIncludedTime++;
690                 }
691             } else {
692                 //If the time is in a range excluded by this calendar, we can
693 // move to the end of the excluded time range and continue
694 // testing from there. Otherwise, if nextIncludedTime is
695 // excluded by the baseCalendar, ask it the next time it
696 // includes and begin testing from there. Failing this, add one
697 // millisecond and continue testing.
698 if (nextIncludedTime <
699                         getTimeRangeStartingTimeInMillis(nextIncludedTime)) {
700                     nextIncludedTime =
701                         getTimeRangeStartingTimeInMillis(nextIncludedTime);
702                 } else if (nextIncludedTime >
703                         getTimeRangeEndingTimeInMillis(nextIncludedTime)) {
704                     //(move to start of next day)
705 nextIncludedTime = getEndOfDayJavaCalendar(nextIncludedTime).getTime().getTime();
706                     nextIncludedTime += 1l;
707                 } else if ((getBaseCalendar() != null) &&
708                         (!getBaseCalendar().isTimeIncluded(nextIncludedTime))){
709                     nextIncludedTime =
710                         getBaseCalendar().getNextIncludedTime(nextIncludedTime);
711                 } else {
712                     nextIncludedTime++;
713                 }
714             }
715         }
716         
717         return nextIncludedTime;
718     }
719
720     /**
721      * Returns the start time of the time range (in milliseconds) of the day
722      * specified in <CODE>timeInMillis</CODE>
723      *
724      * @param timeInMillis a time containing the desired date for the starting
725      * time of the time range.
726      * @return a date/time (in milliseconds) representing the start time of the
727      * time range for the specified date.
728      */
729     public long getTimeRangeStartingTimeInMillis(long timeInMillis) {
730         Calendar rangeStartingTime = createJavaCalendar(timeInMillis);
731         rangeStartingTime.set(Calendar.HOUR_OF_DAY, rangeStartingHourOfDay);
732         rangeStartingTime.set(Calendar.MINUTE, rangeStartingMinute);
733         rangeStartingTime.set(Calendar.SECOND, rangeStartingSecond);
734         rangeStartingTime.set(Calendar.MILLISECOND, rangeStartingMillis);
735         return rangeStartingTime.getTime().getTime();
736     }
737
738     /**
739      * Returns the end time of the time range (in milliseconds) of the day
740      * specified in <CODE>timeInMillis</CODE>
741      *
742      * @param timeInMillis a time containing the desired date for the ending
743      * time of the time range.
744      * @return a date/time (in milliseconds) representing the end time of the
745      * time range for the specified date.
746      */
747     public long getTimeRangeEndingTimeInMillis(long timeInMillis) {
748         Calendar rangeEndingTime = createJavaCalendar(timeInMillis);
749         rangeEndingTime.set(Calendar.HOUR_OF_DAY, rangeEndingHourOfDay);
750         rangeEndingTime.set(Calendar.MINUTE, rangeEndingMinute);
751         rangeEndingTime.set(Calendar.SECOND, rangeEndingSecond);
752         rangeEndingTime.set(Calendar.MILLISECOND, rangeEndingMillis);
753         return rangeEndingTime.getTime().getTime();
754     }
755
756     /**
757      * Indicates whether the time range represents an inverted time range (see
758      * class description).
759      *
760      * @return a boolean indicating whether the time range is inverted
761      */
762     public boolean getInvertTimeRange() {
763         return invertTimeRange;
764     }
765     
766     /**
767      * Indicates whether the time range represents an inverted time range (see
768      * class description).
769      *
770      * @param flag the new value for the <CODE>invertTimeRange</CODE> flag.
771      */
772     public void setInvertTimeRange(boolean flag) {
773         this.invertTimeRange = flag;
774     }
775     
776     /**
777      * Returns a string representing the properties of the
778      * <CODE>DailyCalendar</CODE>
779      *
780      * @return the properteis of the DailyCalendar in a String format
781      */
782     public String toString() {
783         NumberFormat numberFormatter = NumberFormat.getNumberInstance();
784         numberFormatter.setMaximumFractionDigits(0);
785         numberFormatter.setMinimumIntegerDigits(2);
786         StringBuffer buffer = new StringBuffer ();
787         if (name != null) {
788             buffer.append(name).append(": ");
789         }
790         buffer.append("base calendar: [");
791         if (getBaseCalendar() != null) {
792             buffer.append(getBaseCalendar().toString());
793         } else {
794             buffer.append("null");
795         }
796         buffer.append("], time range: '");
797         buffer.append(numberFormatter.format(rangeStartingHourOfDay));
798         buffer.append(":");
799         buffer.append(numberFormatter.format(rangeStartingMinute));
800         buffer.append(":");
801         buffer.append(numberFormatter.format(rangeStartingSecond));
802         buffer.append(":");
803         numberFormatter.setMinimumIntegerDigits(3);
804         buffer.append(numberFormatter.format(rangeStartingMillis));
805         numberFormatter.setMinimumIntegerDigits(2);
806         buffer.append(" - ");
807         buffer.append(numberFormatter.format(rangeEndingHourOfDay));
808         buffer.append(":");
809         buffer.append(numberFormatter.format(rangeEndingMinute));
810         buffer.append(":");
811         buffer.append(numberFormatter.format(rangeEndingSecond));
812         buffer.append(":");
813         numberFormatter.setMinimumIntegerDigits(3);
814         buffer.append(numberFormatter.format(rangeEndingMillis));
815         buffer.append("', inverted: " + invertTimeRange + "]");
816         return buffer.toString();
817     }
818     
819     /**
820      * Helper method to split the given string by the given delimiter.
821      */
822     private String [] split(String string, String delim) {
823         ArrayList result = new ArrayList ();
824         
825         StringTokenizer stringTokenizer = new StringTokenizer (string, delim);
826         while (stringTokenizer.hasMoreTokens()) {
827             result.add(stringTokenizer.nextToken());
828         }
829         
830         return (String [])result.toArray(new String [result.size()]);
831     }
832     
833     /**
834      * Sets the time range for the <CODE>DailyCalendar</CODE> to the times
835      * represented in the specified Strings.
836      *
837      * @param rangeStartingTimeString a String representing the start time of
838      * the time range
839      * @param rangeEndingTimeString a String representing the end time of the
840      * excluded time range
841      */
842     private void setTimeRange(String rangeStartingTimeString,
843                               String rangeEndingTimeString) {
844         String [] rangeStartingTime;
845         int rangeStartingHourOfDay;
846         int rangeStartingMinute;
847         int rangeStartingSecond;
848         int rangeStartingMillis;
849         
850         String [] rangeEndingTime;
851         int rangeEndingHourOfDay;
852         int rangeEndingMinute;
853         int rangeEndingSecond;
854         int rangeEndingMillis;
855         
856         rangeStartingTime = split(rangeStartingTimeString, colon);
857         
858         if ((rangeStartingTime.length < 2) || (rangeStartingTime.length > 4)) {
859             throw new IllegalArgumentException ("Invalid time string '" +
860                     rangeStartingTimeString + "'");
861         }
862         
863         rangeStartingHourOfDay = Integer.parseInt(rangeStartingTime[0]);
864         rangeStartingMinute = Integer.parseInt(rangeStartingTime[1]);
865         if (rangeStartingTime.length > 2) {
866             rangeStartingSecond = Integer.parseInt(rangeStartingTime[2]);
867         } else {
868             rangeStartingSecond = 0;
869         }
870         if (rangeStartingTime.length == 4) {
871             rangeStartingMillis = Integer.parseInt(rangeStartingTime[3]);
872         } else {
873             rangeStartingMillis = 0;
874         }
875         
876         rangeEndingTime = split(rangeEndingTimeString, colon);
877
878         if ((rangeEndingTime.length < 2) || (rangeEndingTime.length > 4)) {
879             throw new IllegalArgumentException ("Invalid time string '" +
880                     rangeEndingTimeString + "'");
881         }
882         
883         rangeEndingHourOfDay = Integer.parseInt(rangeEndingTime[0]);
884         rangeEndingMinute = Integer.parseInt(rangeEndingTime[1]);
885         if (rangeEndingTime.length > 2) {
886             rangeEndingSecond = Integer.parseInt(rangeEndingTime[2]);
887         } else {
888             rangeEndingSecond = 0;
889         }
890         if (rangeEndingTime.length == 4) {
891             rangeEndingMillis = Integer.parseInt(rangeEndingTime[3]);
892         } else {
893             rangeEndingMillis = 0;
894         }
895         
896         setTimeRange(rangeStartingHourOfDay,
897                      rangeStartingMinute,
898                      rangeStartingSecond,
899                      rangeStartingMillis,
900                      rangeEndingHourOfDay,
901                      rangeEndingMinute,
902                      rangeEndingSecond,
903                      rangeEndingMillis);
904     }
905
906     /**
907      * Sets the time range for the <CODE>DailyCalendar</CODE> to the times
908      * represented in the specified values.
909      *
910      * @param rangeStartingHourOfDay the hour of the start of the time range
911      * @param rangeStartingMinute the minute of the start of the time range
912      * @param rangeStartingSecond the second of the start of the time range
913      * @param rangeStartingMillis the millisecond of the start of the time
914      * range
915      * @param rangeEndingHourOfDay the hour of the end of the time range
916      * @param rangeEndingMinute the minute of the end of the time range
917      * @param rangeEndingSecond the second of the end of the time range
918      * @param rangeEndingMillis the millisecond of the start of the time
919      * range
920      */
921     private void setTimeRange(int rangeStartingHourOfDay,
922                               int rangeStartingMinute,
923                               int rangeStartingSecond,
924                               int rangeStartingMillis,
925                               int rangeEndingHourOfDay,
926                               int rangeEndingMinute,
927                               int rangeEndingSecond,
928                               int rangeEndingMillis) {
929         validate(rangeStartingHourOfDay,
930                  rangeStartingMinute,
931                  rangeStartingSecond,
932                  rangeStartingMillis);
933         
934         validate(rangeEndingHourOfDay,
935                  rangeEndingMinute,
936                  rangeEndingSecond,
937                  rangeEndingMillis);
938         
939         Calendar startCal = createJavaCalendar();
940         startCal.set(Calendar.HOUR_OF_DAY, rangeStartingHourOfDay);
941         startCal.set(Calendar.MINUTE, rangeStartingMinute);
942         startCal.set(Calendar.SECOND, rangeStartingSecond);
943         startCal.set(Calendar.MILLISECOND, rangeStartingMillis);
944         
945         Calendar endCal = createJavaCalendar();
946         endCal.set(Calendar.HOUR_OF_DAY, rangeEndingHourOfDay);
947         endCal.set(Calendar.MINUTE, rangeEndingMinute);
948         endCal.set(Calendar.SECOND, rangeEndingSecond);
949         endCal.set(Calendar.MILLISECOND, rangeEndingMillis);
950         
951         if (!startCal.before(endCal)) {
952             throw new IllegalArgumentException (invalidTimeRange +
953                     rangeStartingHourOfDay + ":" +
954                     rangeStartingMinute + ":" +
955                     rangeStartingSecond + ":" +
956                     rangeStartingMillis + separator +
957                     rangeEndingHourOfDay + ":" +
958                     rangeEndingMinute + ":" +
959                     rangeEndingSecond + ":" +
960                     rangeEndingMillis);
961         }
962         
963         this.rangeStartingHourOfDay = rangeStartingHourOfDay;
964         this.rangeStartingMinute = rangeStartingMinute;
965         this.rangeStartingSecond = rangeStartingSecond;
966         this.rangeStartingMillis = rangeStartingMillis;
967         this.rangeEndingHourOfDay = rangeEndingHourOfDay;
968         this.rangeEndingMinute = rangeEndingMinute;
969         this.rangeEndingSecond = rangeEndingSecond;
970         this.rangeEndingMillis = rangeEndingMillis;
971     }
972     
973     /**
974      * Sets the time range for the <CODE>DailyCalendar</CODE> to the times
975      * represented in the specified <CODE>java.util.Calendar</CODE>s.
976      *
977      * @param rangeStartingCalendar a Calendar containing the start time for
978      * the <CODE>DailyCalendar</CODE>
979      * @param rangeEndingCalendar a Calendar containing the end time for
980      * the <CODE>DailyCalendar</CODE>
981      */
982     private void setTimeRange(Calendar rangeStartingCalendar,
983                               Calendar rangeEndingCalendar) {
984         setTimeRange(
985                 rangeStartingCalendar.get(Calendar.HOUR_OF_DAY),
986                 rangeStartingCalendar.get(Calendar.MINUTE),
987                 rangeStartingCalendar.get(Calendar.SECOND),
988                 rangeStartingCalendar.get(Calendar.MILLISECOND),
989                 rangeEndingCalendar.get(Calendar.HOUR_OF_DAY),
990                 rangeEndingCalendar.get(Calendar.MINUTE),
991                 rangeEndingCalendar.get(Calendar.SECOND),
992                 rangeEndingCalendar.get(Calendar.MILLISECOND));
993     }
994     
995     /**
996      * Sets the time range for the <CODE>DailyCalendar</CODE> to the times
997      * represented in the specified values.
998      *
999      * @param rangeStartingTime the starting time (in milliseconds) for the
1000     * time range
1001     * @param rangeEndingTime the ending time (in milliseconds) for the time
1002     * range
1003     */
1004    private void setTimeRange(long rangeStartingTime,
1005                              long rangeEndingTime) {
1006        setTimeRange(
1007            createJavaCalendar(rangeStartingTime),
1008            createJavaCalendar(rangeEndingTime));
1009    }
1010    
1011    /**
1012     * Checks the specified values for validity as a set of time values.
1013     *
1014     * @param hourOfDay the hour of the time to check (in military (24-hour)
1015     * time)
1016     * @param minute the minute of the time to check
1017     * @param second the second of the time to check
1018     * @param millis the millisecond of the time to check
1019     */
1020    private void validate(int hourOfDay, int minute, int second, int millis) {
1021        if (hourOfDay < 0 || hourOfDay > 23) {
1022            throw new IllegalArgumentException (invalidHourOfDay + hourOfDay);
1023        }
1024        if (minute < 0 || minute > 59) {
1025            throw new IllegalArgumentException (invalidMinute + minute);
1026        }
1027        if (second < 0 || second > 59) {
1028            throw new IllegalArgumentException (invalidSecond + second);
1029        }
1030        if (millis < 0 || millis > 999) {
1031            throw new IllegalArgumentException (invalidMillis + millis);
1032        }
1033    }
1034}

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags