Quartz Scheduler(2.2.1) - Usage of Calendars

Quartz Calendar objects (not java.util.Calendar objects) can be associated with triggers at the time the trigger is defined and stored in the scheduler.

Calendars are useful for excluding blocks of time from the trigger's firing schedule. For instance, you could create a trigger that fires a job every weekday at 9:30 am, but then add a Calendar that excludes all of the business's holidays.

Calendar's can be any serializable object that implements the Calendar interface {shown below).

package org.quartz;
   
public interface Calendar {    
    public boolean isTimeIncluded(long timeStamp);    
    public long getNextIncludedTime(long timeStamp);    
}

Notice that the parameters to these methods are of the long type. These are timestamps in millisecond format. This means that calendars can 'block out' sections of time as narrow as a millisecond. Most likely, you'll be interested in 'blocking-out' entire days. As a convenience, Quartz includes the class org.quartz.impl.HolidayCalendar, which does just that.

Calendars must be instantiated and registered with the scheduler via the addCalendar(..) method. If you use HolidayCalendar, after instantiating it, you should use its addExcludedDate(Date date) method in order to populate it with the days you wish to have excluded from scheduling. The same calendar instance can be used with multiple triggers as shown in the example below:

HolidayCalendar cal = new HolidayCalendar();    
cal.addExcludedDate( someDate );    
cal.addExcludedDate( someOtherDate );    
sched.addCalendar("myHolidays", cal, false);    
Trigger t = newTrigger()    
    .withIdentity("myTrigger")    
    .forJob("myJob")    
    .withSchedule(dailyAtHourAndMinute(9, 30)) // execute job daily at 9:30    
    .modifiedByCalendar("myHolidays") // but not on holidays    
    .build();    
// .. schedule job with trigger    
Trigger t2 = newTrigger()    
    .withIdentity("myTrigger2")    
    .forJob("myJob2")    
    .withSchedule(dailyAtHourAndMinute(11, 30)) // execute job daily at 11:30    
    .modifiedByCalendar("myHolidays") // but not on holidays    
    .build();    
// .. schedule job with trigger2

The code above creates two triggers, each scheduled to fire daily. However, any of the firings that would have occurred during the period excluded by the calendar will be skipped.

The org.quartz.impl.calendar package provides a number of Calendar implementations that may suit your needs.