Core Scheduling

/**
 * Main factory interface for creating Scheduler instances
 */
interface SchedulerFactory {
    /**
     * Returns a scheduler instance using the default configuration
     * @return the default scheduler instance
     * @throws SchedulerException if scheduler cannot be created
     */
    Scheduler getScheduler() throws SchedulerException;
    
    /**
     * Returns a named scheduler instance
     * @param schedName the name of the scheduler to retrieve
     * @return the named scheduler instance
     * @throws SchedulerException if scheduler cannot be found or created
     */
    Scheduler getScheduler(String schedName) throws SchedulerException;
    
    /**
     * Returns all schedulers managed by this factory
     * @return collection of all scheduler instances
     * @throws SchedulerException if schedulers cannot be retrieved
     */
    Collection<Scheduler> getAllSchedulers() throws SchedulerException;
}

/**
 * Standard implementation of SchedulerFactory using property-based configuration
 */
class StdSchedulerFactory implements SchedulerFactory {
    StdSchedulerFactory();
    StdSchedulerFactory(Properties props) throws SchedulerException;
    StdSchedulerFactory(String fileName) throws SchedulerException;
    
    void initialize() throws SchedulerException;
    void initialize(Properties props) throws SchedulerException;
    void initialize(String filename) throws SchedulerException;
    void initialize(InputStream propertiesStream) throws SchedulerException;
}

// Basic scheduler creation
SchedulerFactory factory = new StdSchedulerFactory();
Scheduler scheduler = factory.getScheduler();

// Custom configuration
Properties props = new Properties();
props.put("org.quartz.scheduler.instanceName", "MyScheduler");
props.put("org.quartz.threadPool.threadCount", "10");
SchedulerFactory customFactory = new StdSchedulerFactory(props);
Scheduler customScheduler = customFactory.getScheduler();

// Configuration from file
SchedulerFactory fileFactory = new StdSchedulerFactory("quartz.properties");
Scheduler fileScheduler = fileFactory.getScheduler();

/**
 * Main interface of a Quartz Scheduler for managing jobs and triggers
 */
interface Scheduler {
    /**
     * Default group name for jobs and triggers when no specific group is provided
     */
    String DEFAULT_GROUP = "DEFAULT";
    
    /**
     * Group name used for jobs during recovery operations
     */
    String DEFAULT_RECOVERY_GROUP = "RECOVERING_JOBS";
    
    /**
     * Group name used for failed-over jobs in clustered environments
     */
    String DEFAULT_FAIL_OVER_GROUP = "FAILED_OVER_JOBS";
}

/**
 * Start the scheduler. Jobs will begin executing according to their triggers.
 * @throws SchedulerException if scheduler cannot be started
 */
void start() throws SchedulerException;

/**
 * Start the scheduler after the specified delay in seconds
 * @param seconds delay before starting the scheduler
 * @throws SchedulerException if scheduler cannot be started
 */
void startDelayed(int seconds) throws SchedulerException;

/**
 * Temporarily halt the scheduler. Jobs will not execute but remain scheduled.
 * @throws SchedulerException if scheduler cannot be put in standby
 */
void standby() throws SchedulerException;

/**
 * Shutdown the scheduler. Waits for currently executing jobs to complete.
 * @throws SchedulerException if scheduler cannot be shutdown
 */
void shutdown() throws SchedulerException;

/**
 * Shutdown the scheduler with option to wait for jobs
 * @param waitForJobsToComplete if true, waits for running jobs to finish
 * @throws SchedulerException if scheduler cannot be shutdown
 */
void shutdown(boolean waitForJobsToComplete) throws SchedulerException;

/**
 * Check if the scheduler has been started
 * @return true if scheduler is started and operational
 * @throws SchedulerException if scheduler state cannot be determined
 */
boolean isStarted() throws SchedulerException;

/**
 * Check if the scheduler is in standby mode
 * @return true if scheduler is in standby mode
 * @throws SchedulerException if scheduler state cannot be determined
 */
boolean isInStandbyMode() throws SchedulerException;

/**
 * Check if the scheduler has been shutdown
 * @return true if scheduler has been shutdown
 * @throws SchedulerException if scheduler state cannot be determined
 */
boolean isShutdown() throws SchedulerException;

Scheduler scheduler = new StdSchedulerFactory().getScheduler();

// Start scheduler
scheduler.start();

// Check status
if (scheduler.isStarted()) {
    System.out.println("Scheduler is running");
}

// Put in standby (pause all execution)
scheduler.standby();

// Resume from standby
scheduler.start();

// Shutdown gracefully
scheduler.shutdown(true); // Wait for jobs to complete

/**
 * Schedule a job with an associated trigger
 * @param jobDetail the job to be scheduled
 * @param trigger the trigger that will fire the job
 * @return the date/time the job was first scheduled to run
 * @throws SchedulerException if job cannot be scheduled
 */
Date scheduleJob(JobDetail jobDetail, Trigger trigger) throws SchedulerException;

/**
 * Schedule a trigger for an existing job
 * @param trigger the trigger to schedule (must reference existing job)
 * @return the date/time the trigger was first scheduled to fire
 * @throws SchedulerException if trigger cannot be scheduled
 */
Date scheduleJob(Trigger trigger) throws SchedulerException;

/**
 * Schedule multiple jobs and their associated triggers atomically
 * @param triggersAndJobs map of jobs to their triggers
 * @param replace if true, replace existing jobs/triggers with same keys
 * @throws SchedulerException if jobs cannot be scheduled
 */
void scheduleJobs(Map<JobDetail, Set<? extends Trigger>> triggersAndJobs, boolean replace) throws SchedulerException;

// Basic job scheduling
JobDetail job = newJob(MyJob.class)
    .withIdentity("job1", "group1")
    .build();

Trigger trigger = newTrigger()
    .withIdentity("trigger1", "group1")
    .startNow()
    .withSchedule(simpleSchedule()
        .withIntervalInSeconds(30)
        .repeatForever())
    .build();

Date firstFireTime = scheduler.scheduleJob(job, trigger);

// Schedule additional trigger for existing job
Trigger additionalTrigger = newTrigger()
    .withIdentity("trigger2", "group1")
    .forJob("job1", "group1")
    .withSchedule(cronSchedule("0 0 12 * * ?")) // Daily at noon
    .build();

scheduler.scheduleJob(additionalTrigger);

// Batch scheduling
Map<JobDetail, Set<? extends Trigger>> jobsAndTriggers = new HashMap<>();
jobsAndTriggers.put(job1, Set.of(trigger1, trigger2));
jobsAndTriggers.put(job2, Set.of(trigger3));
scheduler.scheduleJobs(jobsAndTriggers, false);

/**
 * Add a job to the scheduler without scheduling it (durable job)
 * @param jobDetail the job to add
 * @param replace if true, replace existing job with same key
 * @throws SchedulerException if job cannot be added
 */
void addJob(JobDetail jobDetail, boolean replace) throws SchedulerException;

/**
 * Delete a job and all associated triggers
 * @param jobKey the key identifying the job to delete
 * @return true if job was found and deleted
 * @throws SchedulerException if job cannot be deleted
 */
boolean deleteJob(JobKey jobKey) throws SchedulerException;

/**
 * Delete multiple jobs and their associated triggers
 * @param jobKeys list of job keys to delete
 * @return true if all jobs were found and deleted
 * @throws SchedulerException if jobs cannot be deleted
 */
boolean deleteJobs(List<JobKey> jobKeys) throws SchedulerException;

/**
 * Trigger a job execution immediately (ignoring associated triggers)
 * @param jobKey the key identifying the job to trigger
 * @throws SchedulerException if job cannot be triggered
 */
void triggerJob(JobKey jobKey) throws SchedulerException;

/**
 * Trigger a job execution with additional job data
 * @param jobKey the key identifying the job to trigger
 * @param data additional data to pass to the job
 * @throws SchedulerException if job cannot be triggered
 */
void triggerJob(JobKey jobKey, JobDataMap data) throws SchedulerException;

// Add durable job (persists without triggers)
JobDetail durableJob = newJob(MaintenanceJob.class)
    .withIdentity("maintenance", "system")
    .storeDurably()
    .build();
scheduler.addJob(durableJob, false);

// Manual job triggering
scheduler.triggerJob(jobKey("maintenance", "system"));

// Trigger with additional data
JobDataMap additionalData = new JobDataMap();
additionalData.put("urgent", true);
scheduler.triggerJob(jobKey("maintenance", "system"), additionalData);

// Delete jobs
scheduler.deleteJob(jobKey("job1", "group1"));
scheduler.deleteJobs(List.of(
    jobKey("job1", "group1"),
    jobKey("job2", "group1")
));

/**
 * Get metadata about this scheduler instance
 * @return scheduler metadata including version, status, capabilities
 * @throws SchedulerException if metadata cannot be retrieved
 */
SchedulerMetaData getMetaData() throws SchedulerException;

/**
 * Get the scheduler's application context
 * @return context map for sharing data across jobs
 * @throws SchedulerException if context cannot be retrieved
 */
SchedulerContext getContext() throws SchedulerException;

/**
 * Get the scheduler's unique name
 * @return scheduler instance name
 * @throws SchedulerException if name cannot be retrieved
 */
String getSchedulerName() throws SchedulerException;

/**
 * Get the scheduler's instance ID
 * @return scheduler instance identifier
 * @throws SchedulerException if instance ID cannot be retrieved
 */
String getSchedulerInstanceId() throws SchedulerException;

// Get scheduler information
SchedulerMetaData metaData = scheduler.getMetaData();
System.out.println("Scheduler: " + metaData.getSchedulerName());
System.out.println("Version: " + metaData.getVersion());
System.out.println("Started: " + metaData.getRunningSince());

// Use scheduler context for shared data
SchedulerContext context = scheduler.getContext();
context.put("applicationVersion", "1.0.0");
context.put("configuration", appConfig);