Calendar Management

/**
 * Interface for calendars that can exclude time periods from trigger schedules
 */
interface Calendar extends Serializable, Cloneable {
    /**
     * Determine whether the given time is included by the calendar
     * @param timeStamp the time to check (in milliseconds)
     * @return true if the time is included, false if excluded
     */
    boolean isTimeIncluded(long timeStamp);
    
    /**
     * Determine the next time that is included by the calendar
     * @param timeStamp the starting time (in milliseconds)
     * @return the next included time after the given time
     */
    long getNextIncludedTime(long timeStamp);
    
    /**
     * Get the description of this calendar
     * @return calendar description
     */
    String getDescription();
    
    /**
     * Set the description of this calendar
     * @param description the calendar description
     */
    void setDescription(String description);
    
    /**
     * Get the base calendar that this calendar wraps
     * @return the base calendar, or null if none
     */
    Calendar getBaseCalendar();
    
    /**
     * Set a base calendar to chain with this calendar
     * @param baseCalendar the base calendar to chain
     */
    void setBaseCalendar(Calendar baseCalendar);
    
    /**
     * Create a copy of this calendar
     * @return cloned calendar instance
     */
    Object clone();
}

/**
 * Abstract base class for calendar implementations
 */
abstract class BaseCalendar implements Calendar {
    /**
     * Create a base calendar with optional description
     */
    BaseCalendar();
    BaseCalendar(String description);
    BaseCalendar(Calendar baseCalendar);
    BaseCalendar(Calendar baseCalendar, String description);
    
    /**
     * Get the time zone for this calendar
     * @return the time zone
     */
    TimeZone getTimeZone();
    
    /**
     * Set the time zone for this calendar
     * @param timeZone the time zone to use
     */
    void setTimeZone(TimeZone timeZone);
}

/**
 * Calendar that excludes specific days of the year
 */
class AnnualCalendar extends BaseCalendar {
    /**
     * Create annual calendar with optional base calendar
     */
    AnnualCalendar();
    AnnualCalendar(Calendar baseCalendar);
    AnnualCalendar(Calendar baseCalendar, String description);
    
    /**
     * Add a day to exclude from the calendar
     * @param excludedDay the day to exclude (Calendar format)
     */
    void setDayExcluded(Calendar excludedDay, boolean exclude);
    
    /**
     * Check if a day is excluded
     * @param day the day to check
     * @return true if the day is excluded
     */
    boolean isDayExcluded(Calendar day);
    
    /**
     * Get all excluded days
     * @return array of excluded days
     */
    Calendar[] getExcludedDays();
}

/**
 * Calendar that excludes times based on cron expressions
 */
class CronCalendar extends BaseCalendar {
    /**
     * Create cron calendar with cron expression
     * @param cronExpression the cron expression for exclusions
     */
    CronCalendar(String cronExpression) throws ParseException;
    CronCalendar(Calendar baseCalendar, String cronExpression) throws ParseException;
    
    /**
     * Set the cron expression for this calendar
     * @param cronExpression the cron expression
     * @throws ParseException if cron expression is invalid
     */
    void setCronExpression(String cronExpression) throws ParseException;
    
    /**
     * Get the cron expression
     * @return the cron expression string
     */
    String getCronExpression();
    
    /**
     * Get the cron expression object
     * @return the CronExpression instance
     */
    CronExpression getCronExpressionObject();
}

/**
 * Calendar that excludes time ranges within days
 */
class DailyCalendar extends BaseCalendar {
    /**
     * Create daily calendar with time range exclusion
     * @param rangeStartingTime start time (format "HH:mm:ss:SSS")
     * @param rangeEndingTime end time (format "HH:mm:ss:SSS")
     */
    DailyCalendar(String rangeStartingTime, String rangeEndingTime);
    DailyCalendar(Calendar baseCalendar, String rangeStartingTime, String rangeEndingTime);
    
    /**
     * Create daily calendar with time range exclusion
     * @param rangeStartingTimeInMillis start time in milliseconds from midnight
     * @param rangeEndingTimeInMillis end time in milliseconds from midnight
     */
    DailyCalendar(long rangeStartingTimeInMillis, long rangeEndingTimeInMillis);
    DailyCalendar(Calendar baseCalendar, long rangeStartingTimeInMillis, long rangeEndingTimeInMillis);
    
    /**
     * Get the excluded time range start
     * @return start time in milliseconds from midnight
     */
    long getRangeStartingTimeInMillis();
    
    /**
     * Get the excluded time range end
     * @return end time in milliseconds from midnight
     */
    long getRangeEndingTimeInMillis();
    
    /**
     * Set whether to invert the time range (exclude everything except the range)
     * @param invert true to invert the range
     */
    void setInvertTimeRange(boolean invert);
    
    /**
     * Check if the time range is inverted
     * @return true if range is inverted
     */
    boolean getInvertTimeRange();
}

/**
 * Calendar that excludes specific dates
 */
class HolidayCalendar extends BaseCalendar {
    /**
     * Create holiday calendar
     */
    HolidayCalendar();
    HolidayCalendar(Calendar baseCalendar);
    HolidayCalendar(Calendar baseCalendar, String description);
    
    /**
     * Add a date to exclude
     * @param excludedDate the date to exclude
     */
    void addExcludedDate(Date excludedDate);
    
    /**
     * Remove a date from exclusions
     * @param dateToRemove the date to remove from exclusions
     */
    void removeExcludedDate(Date dateToRemove);
    
    /**
     * Get all excluded dates
     * @return sorted set of excluded dates
     */
    SortedSet<Date> getExcludedDates();
    
    /**
     * Check if a date is excluded
     * @param dateToCheck the date to check
     * @return true if the date is excluded
     */
    boolean isDateExcluded(Date dateToCheck);
}

/**
 * Calendar that excludes specific days of the month
 */
class MonthlyCalendar extends BaseCalendar {
    /**
     * Create monthly calendar
     */
    MonthlyCalendar();
    MonthlyCalendar(Calendar baseCalendar);
    MonthlyCalendar(Calendar baseCalendar, String description);
    
    /**
     * Set whether a day of month is excluded
     * @param day day of month (1-31)
     * @param exclude true to exclude the day
     */
    void setDayExcluded(int day, boolean exclude);
    
    /**
     * Check if a day of month is excluded
     * @param day day of month (1-31)
     * @return true if the day is excluded
     */
    boolean isDayExcluded(int day);
    
    /**
     * Get all excluded days of month
     * @return array of excluded days (1-31)
     */
    boolean[] getExcludedDays();
}

/**
 * Calendar that excludes specific days of the week
 */
class WeeklyCalendar extends BaseCalendar {
    /**
     * Create weekly calendar
     */
    WeeklyCalendar();
    WeeklyCalendar(Calendar baseCalendar);
    WeeklyCalendar(Calendar baseCalendar, String description);
    
    /**
     * Set whether a day of week is excluded
     * @param wday day of week (Calendar.SUNDAY = 1, Calendar.MONDAY = 2, etc.)
     * @param exclude true to exclude the day
     */
    void setDayExcluded(int wday, boolean exclude);
    
    /**
     * Check if a day of week is excluded
     * @param wday day of week constant
     * @return true if the day is excluded
     */
    boolean isDayExcluded(int wday);
    
    /**
     * Get all excluded days of week
     * @return array of excluded days (indexed by Calendar day constants)
     */
    boolean[] getExcludedDays();
}

import org.quartz.*;
import org.quartz.impl.calendar.*;
import java.util.Calendar;
import java.util.Date;

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

// Add specific holiday dates
Calendar cal = Calendar.getInstance();
cal.set(2024, Calendar.JANUARY, 1); // New Year's Day
holidays.addExcludedDate(cal.getTime());
cal.set(2024, Calendar.JULY, 4); // Independence Day
holidays.addExcludedDate(cal.getTime());
cal.set(2024, Calendar.DECEMBER, 25); // Christmas
holidays.addExcludedDate(cal.getTime());

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

// Create weekend calendar
WeeklyCalendar weekends = new WeeklyCalendar();
weekends.setDescription("Weekends");
weekends.setDayExcluded(Calendar.SATURDAY, true);
weekends.setDayExcluded(Calendar.SUNDAY, true);

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

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

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

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

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

// Use calendar with trigger
Trigger trigger = newTrigger()
    .withIdentity("businessTrigger", "reports")
    .withSchedule(simpleSchedule()
        .withIntervalInHours(1)
        .repeatForever())
    .modifiedByCalendar("businessDays") // Apply calendar exclusions
    .build();

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

// Monthly calendar to exclude first day of month
MonthlyCalendar monthEnd = new MonthlyCalendar();
monthEnd.setDescription("Month End Processing");
monthEnd.setDayExcluded(1, true); // Exclude 1st day of month
scheduler.addCalendar("monthEnd", monthEnd, false, false);

class TimeOfDay implements Serializable {
    TimeOfDay(int hour, int minute);
    TimeOfDay(int hour, int minute, int second);
    
    int getHour();
    int getMinute();
    int getSecond();
    
    /**
     * Convert to seconds since midnight
     * @return seconds since midnight
     */
    int getSecondsOfDay();
    
    /**
     * Check if this time is before another time
     * @param timeOfDay the time to compare
     * @return true if this time is before the other
     */
    boolean before(TimeOfDay timeOfDay);
    
    /**
     * Check if this time is after another time
     * @param timeOfDay the time to compare
     * @return true if this time is after the other
     */
    boolean after(TimeOfDay timeOfDay);
    
    /**
     * Create TimeOfDay from hour and minute
     * @param hour hour (0-23)
     * @param minute minute (0-59)
     * @return TimeOfDay instance
     */
    static TimeOfDay hourAndMinuteOfDay(int hour, int minute);
    
    /**
     * Create TimeOfDay from hour, minute, and second
     * @param hour hour (0-23)
     * @param minute minute (0-59)
     * @param second second (0-59)
     * @return TimeOfDay instance
     */
    static TimeOfDay hourMinuteAndSecondOfDay(int hour, int minute, int second);
}