Trigger Management

/**
 * Base interface for all trigger types that control job execution timing
 */
interface Trigger extends Serializable, Cloneable, Comparable<Trigger> {
    /**
     * Wildcard for matching all groups
     */
    String DEFAULT_GROUP = "DEFAULT";
    
    /**
     * Smart misfire policy - let Quartz decide how to handle misfires
     */
    int MISFIRE_INSTRUCTION_SMART_POLICY = 0;
    
    /**
     * Ignore misfire policy - execute as if no misfire occurred
     */
    int MISFIRE_INSTRUCTION_IGNORE_MISFIRE_POLICY = -1;
    
    /**
     * Default trigger priority
     */
    int DEFAULT_PRIORITY = 5;
    
    /**
     * Possible states for a trigger
     */
    enum TriggerState {
        NONE, NORMAL, PAUSED, COMPLETE, ERROR, BLOCKED
    }
    
    /**
     * Instructions that can be returned by trigger completion
     */
    enum CompletedExecutionInstruction {
        NOOP, RE_EXECUTE_JOB, SET_TRIGGER_COMPLETE, DELETE_TRIGGER,
        SET_ALL_JOB_TRIGGERS_COMPLETE, SET_TRIGGER_ERROR, SET_ALL_JOB_TRIGGERS_ERROR
    }
    
    /**
     * Get the unique key that identifies this trigger
     * @return the trigger's key (name and group)
     */
    TriggerKey getKey();
    
    /**
     * Get the key of the job this trigger fires
     * @return the associated job's key
     */
    JobKey getJobKey();
    
    /**
     * Get the trigger's human-readable description
     * @return description or null if none set
     */
    String getDescription();
    
    /**
     * Get the name of the calendar modifying this trigger's schedule
     * @return calendar name or null if none associated
     */
    String getCalendarName();
    
    /**
     * Get the job data map for this trigger
     * @return trigger's job data map (never null)
     */
    JobDataMap getJobDataMap();
    
    /**
     * Get the trigger's priority for execution ordering
     * @return priority value (higher numbers = higher priority)
     */
    int getPriority();
    
    /**
     * Get the time this trigger should start firing
     * @return start time
     */
    Date getStartTime();
    
    /**
     * Get the time this trigger should stop firing
     * @return end time or null if no end time
     */
    Date getEndTime();
    
    /**
     * Get the next time this trigger will fire
     * @return next fire time or null if trigger won't fire again
     */
    Date getNextFireTime();
    
    /**
     * Get the previous time this trigger fired
     * @return previous fire time or null if never fired
     */
    Date getPreviousFireTime();
    
    /**
     * Get the next fire time after the given time
     * @param afterTime time to search after
     * @return next fire time after the given time
     */
    Date getFireTimeAfter(Date afterTime);
    
    /**
     * Get the final time this trigger will fire
     * @return final fire time or null if fires indefinitely
     */
    Date getFinalFireTime();
    
    /**
     * Get the misfire instruction for this trigger
     * @return misfire instruction code
     */
    int getMisfireInstruction();
    
    /**
     * Check if this trigger may fire again
     * @return true if trigger has remaining firings
     */
    boolean mayFireAgain();
    
    /**
     * Get a TriggerBuilder to create a similar trigger
     * @return builder configured like this trigger
     */
    TriggerBuilder<? extends Trigger> getTriggerBuilder();
    
    /**
     * Get a ScheduleBuilder to recreate this trigger's schedule
     * @return schedule builder for this trigger type
     */
    ScheduleBuilder<? extends Trigger> getScheduleBuilder();
}

/**
 * Builder for Trigger instances using fluent interface
 */
class TriggerBuilder<T extends Trigger> {
    /**
     * Create a new TriggerBuilder
     * @return new builder instance
     */
    static TriggerBuilder<Trigger> newTrigger();
    
    /**
     * Set the trigger's identity using name only (uses DEFAULT_GROUP)
     * @param name the trigger name
     * @return this builder for method chaining
     */
    TriggerBuilder<T> withIdentity(String name);
    
    /**
     * Set the trigger's identity using name and group
     * @param name the trigger name
     * @param group the trigger group
     * @return this builder for method chaining
     */
    TriggerBuilder<T> withIdentity(String name, String group);
    
    /**
     * Set the trigger's identity using a TriggerKey
     * @param triggerKey the complete trigger key
     * @return this builder for method chaining
     */
    TriggerBuilder<T> withIdentity(TriggerKey triggerKey);
    
    /**
     * Set the trigger's description
     * @param triggerDescription human-readable description
     * @return this builder for method chaining
     */
    TriggerBuilder<T> withDescription(String triggerDescription);
    
    /**
     * Set the trigger's priority (default is 5)
     * @param triggerPriority priority value (higher = more important)
     * @return this builder for method chaining
     */
    TriggerBuilder<T> withPriority(int triggerPriority);
    
    /**
     * Associate a calendar with this trigger
     * @param calName name of calendar to modify trigger schedule
     * @return this builder for method chaining
     */
    TriggerBuilder<T> modifiedByCalendar(String calName);
    
    /**
     * Set the trigger start time
     * @param triggerStartTime when the trigger should start firing
     * @return this builder for method chaining
     */
    TriggerBuilder<T> startAt(Date triggerStartTime);
    
    /**
     * Set the trigger to start immediately
     * @return this builder for method chaining
     */
    TriggerBuilder<T> startNow();
    
    /**
     * Set the trigger end time
     * @param triggerEndTime when the trigger should stop firing
     * @return this builder for method chaining
     */
    TriggerBuilder<T> endAt(Date triggerEndTime);
    
    /**
     * Set the trigger's schedule using a ScheduleBuilder
     * @param schedBuilder the schedule builder defining firing pattern
     * @return typed builder for the schedule type
     */
    <SBT extends T> TriggerBuilder<SBT> withSchedule(ScheduleBuilder<SBT> schedBuilder);
    
    /**
     * Associate trigger with a job using JobKey
     * @param keyOfJobToFire the job key
     * @return this builder for method chaining
     */
    TriggerBuilder<T> forJob(JobKey keyOfJobToFire);
    
    /**
     * Associate trigger with a job using name (DEFAULT_GROUP)
     * @param jobName the job name
     * @return this builder for method chaining
     */
    TriggerBuilder<T> forJob(String jobName);
    
    /**
     * Associate trigger with a job using name and group
     * @param jobName the job name
     * @param jobGroup the job group
     * @return this builder for method chaining
     */
    TriggerBuilder<T> forJob(String jobName, String jobGroup);
    
    /**
     * Associate trigger with a job using JobDetail
     * @param jobDetail the job detail
     * @return this builder for method chaining
     */
    TriggerBuilder<T> forJob(JobDetail jobDetail);
    
    /**
     * Add data to the trigger's job data map
     * @param key the data key
     * @param value the data value
     * @return this builder for method chaining
     */
    TriggerBuilder<T> usingJobData(String key, String value);
    
    /**
     * Add integer data to the trigger's job data map
     * @param key the data key
     * @param value the integer value
     * @return this builder for method chaining
     */
    TriggerBuilder<T> usingJobData(String key, Integer value);
    
    /**
     * Add long data to the trigger's job data map
     * @param key the data key
     * @param value the long value
     * @return this builder for method chaining
     */
    TriggerBuilder<T> usingJobData(String key, Long value);
    
    /**
     * Add float data to the trigger's job data map
     * @param key the data key
     * @param value the float value
     * @return this builder for method chaining
     */
    TriggerBuilder<T> usingJobData(String key, Float value);
    
    /**
     * Add double data to the trigger's job data map
     * @param key the data key
     * @param value the double value
     * @return this builder for method chaining
     */
    TriggerBuilder<T> usingJobData(String key, Double value);
    
    /**
     * Add boolean data to the trigger's job data map
     * @param key the data key
     * @param value the boolean value
     * @return this builder for method chaining
     */
    TriggerBuilder<T> usingJobData(String key, Boolean value);
    
    /**
     * Set the trigger's entire job data map
     * @param newJobDataMap the job data map
     * @return this builder for method chaining
     */
    TriggerBuilder<T> usingJobData(JobDataMap newJobDataMap);
    
    /**
     * Build the trigger instance
     * @return the configured trigger
     */
    T build();
}

// Basic trigger creation
Trigger simpleTrigger = newTrigger()
    .withIdentity("trigger1", "group1")
    .withDescription("Daily report trigger")
    .startNow()
    .withSchedule(simpleSchedule()
        .withIntervalInMinutes(60)
        .repeatForever())
    .forJob("reportJob", "group1")
    .build();

// Trigger with advanced configuration
Trigger complexTrigger = newTrigger()
    .withIdentity("complexTrigger", "processing")
    .withDescription("Complex processing trigger")
    .withPriority(10) // High priority
    .startAt(DateBuilder.futureDate(5, DateBuilder.IntervalUnit.MINUTE))
    .endAt(DateBuilder.futureDate(1, DateBuilder.IntervalUnit.HOUR))
    .modifiedByCalendar("businessHours")
    .usingJobData("mode", "batch")
    .usingJobData("maxRecords", 1000)
    .usingJobData("retryEnabled", true)
    .forJob(jobKey("dataProcessor", "processing"))
    .withSchedule(cronSchedule("0 */15 9-17 * * MON-FRI"))
    .build();

// Static imports for cleaner syntax
import static org.quartz.TriggerBuilder.*;
import static org.quartz.SimpleScheduleBuilder.*;
import static org.quartz.CronScheduleBuilder.*;

Trigger cleanTrigger = newTrigger()
    .withIdentity("myTrigger")
    .forJob("myJob")
    .withSchedule(repeatSecondlyForever(30))
    .build();

/**
 * Uniquely identifies a Trigger within a Scheduler
 */
class TriggerKey extends Key<TriggerKey> {
    /**
     * Create a TriggerKey with name in the default group
     * @param name the trigger name
     */
    TriggerKey(String name);
    
    /**
     * Create a TriggerKey with name and group
     * @param name the trigger name
     * @param group the trigger group
     */
    TriggerKey(String name, String group);
    
    /**
     * Static factory method for TriggerKey with default group
     * @param name the trigger name
     * @return new TriggerKey instance
     */
    static TriggerKey triggerKey(String name);
    
    /**
     * Static factory method for TriggerKey with group
     * @param name the trigger name
     * @param group the trigger group
     * @return new TriggerKey instance
     */
    static TriggerKey triggerKey(String name, String group);
}

/**
 * Remove a trigger from the scheduler
 * @param triggerKey the trigger to remove
 * @return true if trigger was found and removed
 * @throws SchedulerException if trigger cannot be removed
 */
boolean unscheduleJob(TriggerKey triggerKey) throws SchedulerException;

/**
 * Remove multiple triggers from the scheduler
 * @param triggerKeys list of triggers to remove
 * @return true if all triggers were found and removed
 * @throws SchedulerException if triggers cannot be removed
 */
boolean unscheduleJobs(List<TriggerKey> triggerKeys) throws SchedulerException;

/**
 * Replace an existing trigger with a new one
 * @param triggerKey the trigger to replace
 * @param newTrigger the replacement trigger
 * @return the first fire time of the new trigger
 * @throws SchedulerException if trigger cannot be replaced
 */
Date rescheduleJob(TriggerKey triggerKey, Trigger newTrigger) throws SchedulerException;

/**
 * Pause a specific trigger
 * @param triggerKey the trigger to pause
 * @throws SchedulerException if trigger cannot be paused
 */
void pauseTrigger(TriggerKey triggerKey) throws SchedulerException;

/**
 * Pause all triggers in a group
 * @param groupName the trigger group to pause
 * @throws SchedulerException if triggers cannot be paused
 */
void pauseTriggers(GroupMatcher<TriggerKey> matcher) throws SchedulerException;

/**
 * Resume a specific trigger
 * @param triggerKey the trigger to resume
 * @throws SchedulerException if trigger cannot be resumed
 */
void resumeTrigger(TriggerKey triggerKey) throws SchedulerException;

/**
 * Resume all triggers in a group
 * @param groupName the trigger group to resume
 * @throws SchedulerException if triggers cannot be resumed
 */
void resumeTriggers(GroupMatcher<TriggerKey> matcher) throws SchedulerException;

/**
 * Get the current state of a trigger
 * @param triggerKey the trigger to check
 * @return the trigger's current state
 * @throws SchedulerException if trigger state cannot be determined
 */
TriggerState getTriggerState(TriggerKey triggerKey) throws SchedulerException;

/**
 * Get trigger details
 * @param triggerKey the trigger to retrieve
 * @return the trigger instance or null if not found
 * @throws SchedulerException if trigger cannot be retrieved
 */
Trigger getTrigger(TriggerKey triggerKey) throws SchedulerException;

// Trigger state management
TriggerKey triggerKey = triggerKey("myTrigger", "myGroup");

// Check current state
TriggerState state = scheduler.getTriggerState(triggerKey);
if (state == TriggerState.NORMAL) {
    System.out.println("Trigger is active");
}

// Pause trigger
scheduler.pauseTrigger(triggerKey);

// Resume trigger
scheduler.resumeTrigger(triggerKey);

// Replace trigger with new schedule
Trigger newTrigger = newTrigger()
    .withIdentity(triggerKey)
    .forJob("myJob", "myGroup")
    .withSchedule(cronSchedule("0 0 12 * * ?")) // Daily at noon
    .build();

Date nextFire = scheduler.rescheduleJob(triggerKey, newTrigger);

// Remove trigger
boolean removed = scheduler.unscheduleJob(triggerKey);

// Group operations using matchers
scheduler.pauseTriggers(GroupMatcher.groupEquals("reports"));
scheduler.resumeTriggers(GroupMatcher.groupStartsWith("batch"));

/**
 * Trigger that fires at regular intervals
 */
interface SimpleTrigger extends Trigger {
    /**
     * Constant for unlimited repeats
     */
    int REPEAT_INDEFINITELY = -1;
    
    // Misfire instruction constants
    int MISFIRE_INSTRUCTION_FIRE_NOW = 1;
    int MISFIRE_INSTRUCTION_RESCHEDULE_NOW_WITH_EXISTING_REPEAT_COUNT = 2;
    int MISFIRE_INSTRUCTION_RESCHEDULE_NOW_WITH_REMAINING_REPEAT_COUNT = 3;
    int MISFIRE_INSTRUCTION_RESCHEDULE_NEXT_WITH_REMAINING_COUNT = 4;
    int MISFIRE_INSTRUCTION_RESCHEDULE_NEXT_WITH_EXISTING_COUNT = 5;
    
    /**
     * Get the number of times the trigger should repeat
     * @return repeat count or REPEAT_INDEFINITELY
     */
    int getRepeatCount();
    
    /**
     * Get the interval between firings
     * @return interval in milliseconds
     */
    long getRepeatInterval();
    
    /**
     * Get the number of times this trigger has fired
     * @return times triggered count
     */
    int getTimesTriggered();
}

/**
 * Trigger that fires based on cron expressions
 */
interface CronTrigger extends Trigger {
    // Misfire instruction constants
    int MISFIRE_INSTRUCTION_FIRE_ONCE_NOW = 1;
    int MISFIRE_INSTRUCTION_DO_NOTHING = 2;
    
    /**
     * Get the cron expression string
     * @return the cron expression
     */
    String getCronExpression();
    
    /**
     * Get the time zone for cron expression evaluation
     * @return the time zone
     */
    TimeZone getTimeZone();
    
    /**
     * Get the expression summary for display
     * @return human-readable description of the cron expression
     */
    String getExpressionSummary();
}

/**
 * Trigger that fires at calendar-based intervals
 */
interface CalendarIntervalTrigger extends Trigger {
    // Misfire instruction constants
    int MISFIRE_INSTRUCTION_FIRE_ONCE_NOW = 1;
    int MISFIRE_INSTRUCTION_DO_NOTHING = 2;
    
    /**
     * Get the repeat interval unit
     * @return the calendar interval unit
     */
    DateBuilder.IntervalUnit getRepeatIntervalUnit();
    
    /**
     * Get the repeat interval value
     * @return the interval value
     */
    int getRepeatInterval();
    
    /**
     * Get the number of times this trigger has fired
     * @return times triggered count
     */
    int getTimesTriggered();
    
    /**
     * Check if time zone should be preserved across DST changes
     * @return true if time zone is preserved
     */
    boolean isPreserveHourOfDayAcrossDaylightSavings();
    
    /**
     * Check if intervals should skip days when DST changes occur
     * @return true if DST days are skipped
     */
    boolean isSkipDayIfHourDoesNotExist();
}

/**
 * Trigger that fires at intervals during specific days and times
 */
interface DailyTimeIntervalTrigger extends Trigger {
    // Misfire instruction constants
    int MISFIRE_INSTRUCTION_FIRE_ONCE_NOW = 1;
    int MISFIRE_INSTRUCTION_DO_NOTHING = 2;
    
    /**
     * Get the days of week this trigger fires
     * @return set of day numbers (1=Sunday, 7=Saturday)
     */
    Set<Integer> getDaysOfWeek();
    
    /**
     * Get the start time of day
     * @return start time
     */
    TimeOfDay getStartTimeOfDay();
    
    /**
     * Get the end time of day
     * @return end time
     */
    TimeOfDay getEndTimeOfDay();
    
    /**
     * Get the repeat interval
     * @return interval value
     */
    int getRepeatInterval();
    
    /**
     * Get the repeat interval unit
     * @return interval unit (SECOND, MINUTE, HOUR)
     */
    DateBuilder.IntervalUnit getRepeatIntervalUnit();
    
    /**
     * Get the number of times this trigger has fired
     * @return times triggered count
     */
    int getTimesTriggered();
}

// Query trigger information
SimpleTrigger simple = (SimpleTrigger) scheduler.getTrigger(triggerKey("simple1"));
System.out.println("Repeat count: " + simple.getRepeatCount());
System.out.println("Interval: " + simple.getRepeatInterval() + "ms");
System.out.println("Times fired: " + simple.getTimesTriggered());

CronTrigger cron = (CronTrigger) scheduler.getTrigger(triggerKey("cron1"));
System.out.println("Cron expression: " + cron.getCronExpression());
System.out.println("Time zone: " + cron.getTimeZone().getID());
System.out.println("Summary: " + cron.getExpressionSummary());

CalendarIntervalTrigger calendar = (CalendarIntervalTrigger) scheduler.getTrigger(triggerKey("cal1"));
System.out.println("Interval: " + calendar.getRepeatInterval() + " " + 
                   calendar.getRepeatIntervalUnit());

DailyTimeIntervalTrigger daily = (DailyTimeIntervalTrigger) scheduler.getTrigger(triggerKey("daily1"));
System.out.println("Days: " + daily.getDaysOfWeek());
System.out.println("Time: " + daily.getStartTimeOfDay() + " to " + daily.getEndTimeOfDay());