0
# Calendar Management
1

2
Calendar-based exclusion system for excluding specific time periods from trigger firing schedules in Quartz. Calendars provide sophisticated control over when jobs can and cannot execute, supporting business rules like holidays, maintenance windows, and custom blackout periods.
3

4
## Capabilities
5

6
### Calendar Interface
7

8
Base interface for all calendar implementations that define time exclusion rules.
9

10
```java { .api }
11
/**
12
 * Interface for calendars that can exclude time periods from trigger schedules
13
 */
14
interface Calendar extends Serializable, Cloneable {
15
    /**
16
     * Determine whether the given time is included by the calendar
17
     * @param timeStamp the time to check (in milliseconds)
18
     * @return true if the time is included, false if excluded
19
     */
20
    boolean isTimeIncluded(long timeStamp);
21
    
22
    /**
23
     * Determine the next time that is included by the calendar
24
     * @param timeStamp the starting time (in milliseconds)
25
     * @return the next included time after the given time
26
     */
27
    long getNextIncludedTime(long timeStamp);
28
    
29
    /**
30
     * Get the description of this calendar
31
     * @return calendar description
32
     */
33
    String getDescription();
34
    
35
    /**
36
     * Set the description of this calendar
37
     * @param description the calendar description
38
     */
39
    void setDescription(String description);
40
    
41
    /**
42
     * Get the base calendar that this calendar wraps
43
     * @return the base calendar, or null if none
44
     */
45
    Calendar getBaseCalendar();
46
    
47
    /**
48
     * Set a base calendar to chain with this calendar
49
     * @param baseCalendar the base calendar to chain
50
     */
51
    void setBaseCalendar(Calendar baseCalendar);
52
    
53
    /**
54
     * Create a copy of this calendar
55
     * @return cloned calendar instance
56
     */
57
    Object clone();
58
}
59
```
60

61
### BaseCalendar Class
62

63
Abstract base implementation providing common calendar functionality.
64

65
```java { .api }
66
/**
67
 * Abstract base class for calendar implementations
68
 */
69
abstract class BaseCalendar implements Calendar {
70
    /**
71
     * Create a base calendar with optional description
72
     */
73
    BaseCalendar();
74
    BaseCalendar(String description);
75
    BaseCalendar(Calendar baseCalendar);
76
    BaseCalendar(Calendar baseCalendar, String description);
77
    
78
    /**
79
     * Get the time zone for this calendar
80
     * @return the time zone
81
     */
82
    TimeZone getTimeZone();
83
    
84
    /**
85
     * Set the time zone for this calendar
86
     * @param timeZone the time zone to use
87
     */
88
    void setTimeZone(TimeZone timeZone);
89
}
90
```
91

92
### AnnualCalendar Class
93

94
Calendar that excludes specific days of the year annually.
95

96
```java { .api }
97
/**
98
 * Calendar that excludes specific days of the year
99
 */
100
class AnnualCalendar extends BaseCalendar {
101
    /**
102
     * Create annual calendar with optional base calendar
103
     */
104
    AnnualCalendar();
105
    AnnualCalendar(Calendar baseCalendar);
106
    AnnualCalendar(Calendar baseCalendar, String description);
107
    
108
    /**
109
     * Add a day to exclude from the calendar
110
     * @param excludedDay the day to exclude (Calendar format)
111
     */
112
    void setDayExcluded(Calendar excludedDay, boolean exclude);
113
    
114
    /**
115
     * Check if a day is excluded
116
     * @param day the day to check
117
     * @return true if the day is excluded
118
     */
119
    boolean isDayExcluded(Calendar day);
120
    
121
    /**
122
     * Get all excluded days
123
     * @return array of excluded days
124
     */
125
    Calendar[] getExcludedDays();
126
}
127
```
128

129
### CronCalendar Class
130

131
Calendar that uses cron expressions to define exclusion periods.
132

133
```java { .api }
134
/**
135
 * Calendar that excludes times based on cron expressions
136
 */
137
class CronCalendar extends BaseCalendar {
138
    /**
139
     * Create cron calendar with cron expression
140
     * @param cronExpression the cron expression for exclusions
141
     */
142
    CronCalendar(String cronExpression) throws ParseException;
143
    CronCalendar(Calendar baseCalendar, String cronExpression) throws ParseException;
144
    
145
    /**
146
     * Set the cron expression for this calendar
147
     * @param cronExpression the cron expression
148
     * @throws ParseException if cron expression is invalid
149
     */
150
    void setCronExpression(String cronExpression) throws ParseException;
151
    
152
    /**
153
     * Get the cron expression
154
     * @return the cron expression string
155
     */
156
    String getCronExpression();
157
    
158
    /**
159
     * Get the cron expression object
160
     * @return the CronExpression instance
161
     */
162
    CronExpression getCronExpressionObject();
163
}
164
```
165

166
### DailyCalendar Class
167

168
Calendar that excludes time ranges within each day.
169

170
```java { .api }
171
/**
172
 * Calendar that excludes time ranges within days
173
 */
174
class DailyCalendar extends BaseCalendar {
175
    /**
176
     * Create daily calendar with time range exclusion
177
     * @param rangeStartingTime start time (format "HH:mm:ss:SSS")
178
     * @param rangeEndingTime end time (format "HH:mm:ss:SSS")
179
     */
180
    DailyCalendar(String rangeStartingTime, String rangeEndingTime);
181
    DailyCalendar(Calendar baseCalendar, String rangeStartingTime, String rangeEndingTime);
182
    
183
    /**
184
     * Create daily calendar with time range exclusion
185
     * @param rangeStartingTimeInMillis start time in milliseconds from midnight
186
     * @param rangeEndingTimeInMillis end time in milliseconds from midnight
187
     */
188
    DailyCalendar(long rangeStartingTimeInMillis, long rangeEndingTimeInMillis);
189
    DailyCalendar(Calendar baseCalendar, long rangeStartingTimeInMillis, long rangeEndingTimeInMillis);
190
    
191
    /**
192
     * Get the excluded time range start
193
     * @return start time in milliseconds from midnight
194
     */
195
    long getRangeStartingTimeInMillis();
196
    
197
    /**
198
     * Get the excluded time range end
199
     * @return end time in milliseconds from midnight
200
     */
201
    long getRangeEndingTimeInMillis();
202
    
203
    /**
204
     * Set whether to invert the time range (exclude everything except the range)
205
     * @param invert true to invert the range
206
     */
207
    void setInvertTimeRange(boolean invert);
208
    
209
    /**
210
     * Check if the time range is inverted
211
     * @return true if range is inverted
212
     */
213
    boolean getInvertTimeRange();
214
}
215
```
216

217
### HolidayCalendar Class
218

219
Calendar that excludes specific dates (holidays or blackout dates).
220

221
```java { .api }
222
/**
223
 * Calendar that excludes specific dates
224
 */
225
class HolidayCalendar extends BaseCalendar {
226
    /**
227
     * Create holiday calendar
228
     */
229
    HolidayCalendar();
230
    HolidayCalendar(Calendar baseCalendar);
231
    HolidayCalendar(Calendar baseCalendar, String description);
232
    
233
    /**
234
     * Add a date to exclude
235
     * @param excludedDate the date to exclude
236
     */
237
    void addExcludedDate(Date excludedDate);
238
    
239
    /**
240
     * Remove a date from exclusions
241
     * @param dateToRemove the date to remove from exclusions
242
     */
243
    void removeExcludedDate(Date dateToRemove);
244
    
245
    /**
246
     * Get all excluded dates
247
     * @return sorted set of excluded dates
248
     */
249
    SortedSet<Date> getExcludedDates();
250
    
251
    /**
252
     * Check if a date is excluded
253
     * @param dateToCheck the date to check
254
     * @return true if the date is excluded
255
     */
256
    boolean isDateExcluded(Date dateToCheck);
257
}
258
```
259

260
### MonthlyCalendar Class
261

262
Calendar that excludes specific days of the month.
263

264
```java { .api }
265
/**
266
 * Calendar that excludes specific days of the month
267
 */
268
class MonthlyCalendar extends BaseCalendar {
269
    /**
270
     * Create monthly calendar
271
     */
272
    MonthlyCalendar();
273
    MonthlyCalendar(Calendar baseCalendar);
274
    MonthlyCalendar(Calendar baseCalendar, String description);
275
    
276
    /**
277
     * Set whether a day of month is excluded
278
     * @param day day of month (1-31)
279
     * @param exclude true to exclude the day
280
     */
281
    void setDayExcluded(int day, boolean exclude);
282
    
283
    /**
284
     * Check if a day of month is excluded
285
     * @param day day of month (1-31)
286
     * @return true if the day is excluded
287
     */
288
    boolean isDayExcluded(int day);
289
    
290
    /**
291
     * Get all excluded days of month
292
     * @return array of excluded days (1-31)
293
     */
294
    boolean[] getExcludedDays();
295
}
296
```
297

298
### WeeklyCalendar Class
299

300
Calendar that excludes specific days of the week.
301

302
```java { .api }
303
/**
304
 * Calendar that excludes specific days of the week
305
 */
306
class WeeklyCalendar extends BaseCalendar {
307
    /**
308
     * Create weekly calendar
309
     */
310
    WeeklyCalendar();
311
    WeeklyCalendar(Calendar baseCalendar);
312
    WeeklyCalendar(Calendar baseCalendar, String description);
313
    
314
    /**
315
     * Set whether a day of week is excluded
316
     * @param wday day of week (Calendar.SUNDAY = 1, Calendar.MONDAY = 2, etc.)
317
     * @param exclude true to exclude the day
318
     */
319
    void setDayExcluded(int wday, boolean exclude);
320
    
321
    /**
322
     * Check if a day of week is excluded
323
     * @param wday day of week constant
324
     * @return true if the day is excluded
325
     */
326
    boolean isDayExcluded(int wday);
327
    
328
    /**
329
     * Get all excluded days of week
330
     * @return array of excluded days (indexed by Calendar day constants)
331
     */
332
    boolean[] getExcludedDays();
333
}
334
```
335

336
**Usage Examples:**
337

338
```java
339
import org.quartz.*;
340
import org.quartz.impl.calendar.*;
341
import java.util.Calendar;
342
import java.util.Date;
343

344
// Create holiday calendar for company holidays
345
HolidayCalendar holidays = new HolidayCalendar();
346
holidays.setDescription("Company Holidays");
347

348
// Add specific holiday dates
349
Calendar cal = Calendar.getInstance();
350
cal.set(2024, Calendar.JANUARY, 1); // New Year's Day
351
holidays.addExcludedDate(cal.getTime());
352
cal.set(2024, Calendar.JULY, 4); // Independence Day
353
holidays.addExcludedDate(cal.getTime());
354
cal.set(2024, Calendar.DECEMBER, 25); // Christmas
355
holidays.addExcludedDate(cal.getTime());
356

357
// Add calendar to scheduler
358
scheduler.addCalendar("holidays", holidays, false, false);
359

360
// Create weekend calendar
361
WeeklyCalendar weekends = new WeeklyCalendar();
362
weekends.setDescription("Weekends");
363
weekends.setDayExcluded(Calendar.SATURDAY, true);
364
weekends.setDayExcluded(Calendar.SUNDAY, true);
365

366
scheduler.addCalendar("weekends", weekends, false, false);
367

368
// Create business hours calendar (exclude nights)
369
DailyCalendar businessHours = new DailyCalendar("18:00:00:000", "08:00:00:000");
370
businessHours.setDescription("After Hours");
371
businessHours.setInvertTimeRange(true); // Exclude everything EXCEPT 8am-6pm
372

373
scheduler.addCalendar("businessHours", businessHours, false, false);
374

375
// Chain calendars - exclude weekends AND holidays
376
WeeklyCalendar businessDays = new WeeklyCalendar(holidays);
377
businessDays.setDescription("Business Days Only");
378
businessDays.setDayExcluded(Calendar.SATURDAY, true);
379
businessDays.setDayExcluded(Calendar.SUNDAY, true);
380

381
scheduler.addCalendar("businessDays", businessDays, false, false);
382

383
// Use calendar with trigger
384
Trigger trigger = newTrigger()
385
    .withIdentity("businessTrigger", "reports")
386
    .withSchedule(simpleSchedule()
387
        .withIntervalInHours(1)
388
        .repeatForever())
389
    .modifiedByCalendar("businessDays") // Apply calendar exclusions
390
    .build();
391

392
// Cron calendar to exclude lunch break
393
CronCalendar lunchBreak = new CronCalendar("0 0 12-13 * * ?");
394
lunchBreak.setDescription("Lunch Break");
395
scheduler.addCalendar("lunchBreak", lunchBreak, false, false);
396

397
// Monthly calendar to exclude first day of month
398
MonthlyCalendar monthEnd = new MonthlyCalendar();
399
monthEnd.setDescription("Month End Processing");
400
monthEnd.setDayExcluded(1, true); // Exclude 1st day of month
401
scheduler.addCalendar("monthEnd", monthEnd, false, false);
402
```
403

404
## Types
405

406
### TimeOfDay Class
407

408
Represents a time of day for use with daily time interval triggers.
409

410
```java { .api }
411
class TimeOfDay implements Serializable {
412
    TimeOfDay(int hour, int minute);
413
    TimeOfDay(int hour, int minute, int second);
414
    
415
    int getHour();
416
    int getMinute();
417
    int getSecond();
418
    
419
    /**
420
     * Convert to seconds since midnight
421
     * @return seconds since midnight
422
     */
423
    int getSecondsOfDay();
424
    
425
    /**
426
     * Check if this time is before another time
427
     * @param timeOfDay the time to compare
428
     * @return true if this time is before the other
429
     */
430
    boolean before(TimeOfDay timeOfDay);
431
    
432
    /**
433
     * Check if this time is after another time
434
     * @param timeOfDay the time to compare
435
     * @return true if this time is after the other
436
     */
437
    boolean after(TimeOfDay timeOfDay);
438
    
439
    /**
440
     * Create TimeOfDay from hour and minute
441
     * @param hour hour (0-23)
442
     * @param minute minute (0-59)
443
     * @return TimeOfDay instance
444
     */
445
    static TimeOfDay hourAndMinuteOfDay(int hour, int minute);
446
    
447
    /**
448
     * Create TimeOfDay from hour, minute, and second
449
     * @param hour hour (0-23)
450
     * @param minute minute (0-59)
451
     * @param second second (0-59)
452
     * @return TimeOfDay instance
453
     */
454
    static TimeOfDay hourMinuteAndSecondOfDay(int hour, int minute, int second);
455
}
456
```