0
# Core Scheduling
1

2
Core scheduler management functionality providing the foundation for all job scheduling operations in Quartz. This includes creating scheduler instances, managing scheduler lifecycle, and performing basic scheduling operations.
3

4
## Capabilities
5

6
### Scheduler Factory
7

8
Creates and manages Scheduler instances. The factory pattern provides flexibility for different scheduler implementations and configurations.
9

10
```java { .api }
11
/**
12
 * Main factory interface for creating Scheduler instances
13
 */
14
interface SchedulerFactory {
15
    /**
16
     * Returns a scheduler instance using the default configuration
17
     * @return the default scheduler instance
18
     * @throws SchedulerException if scheduler cannot be created
19
     */
20
    Scheduler getScheduler() throws SchedulerException;
21
    
22
    /**
23
     * Returns a named scheduler instance
24
     * @param schedName the name of the scheduler to retrieve
25
     * @return the named scheduler instance
26
     * @throws SchedulerException if scheduler cannot be found or created
27
     */
28
    Scheduler getScheduler(String schedName) throws SchedulerException;
29
    
30
    /**
31
     * Returns all schedulers managed by this factory
32
     * @return collection of all scheduler instances
33
     * @throws SchedulerException if schedulers cannot be retrieved
34
     */
35
    Collection<Scheduler> getAllSchedulers() throws SchedulerException;
36
}
37
```
38

39
**Main Implementation:**
40
```java { .api }
41
/**
42
 * Standard implementation of SchedulerFactory using property-based configuration
43
 */
44
class StdSchedulerFactory implements SchedulerFactory {
45
    StdSchedulerFactory();
46
    StdSchedulerFactory(Properties props) throws SchedulerException;
47
    StdSchedulerFactory(String fileName) throws SchedulerException;
48
    
49
    void initialize() throws SchedulerException;
50
    void initialize(Properties props) throws SchedulerException;
51
    void initialize(String filename) throws SchedulerException;
52
    void initialize(InputStream propertiesStream) throws SchedulerException;
53
}
54
```
55

56
**Usage Examples:**
57

58
```java
59
// Basic scheduler creation
60
SchedulerFactory factory = new StdSchedulerFactory();
61
Scheduler scheduler = factory.getScheduler();
62

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

70
// Configuration from file
71
SchedulerFactory fileFactory = new StdSchedulerFactory("quartz.properties");
72
Scheduler fileScheduler = fileFactory.getScheduler();
73
```
74

75
### Scheduler Interface
76

77
The main interface for all scheduling operations. Provides comprehensive control over job and trigger management, scheduler lifecycle, and system state.
78

79
```java { .api }
80
/**
81
 * Main interface of a Quartz Scheduler for managing jobs and triggers
82
 */
83
interface Scheduler {
84
    /**
85
     * Default group name for jobs and triggers when no specific group is provided
86
     */
87
    String DEFAULT_GROUP = "DEFAULT";
88
    
89
    /**
90
     * Group name used for jobs during recovery operations
91
     */
92
    String DEFAULT_RECOVERY_GROUP = "RECOVERING_JOBS";
93
    
94
    /**
95
     * Group name used for failed-over jobs in clustered environments
96
     */
97
    String DEFAULT_FAIL_OVER_GROUP = "FAILED_OVER_JOBS";
98
}
99
```
100

101
### Scheduler Lifecycle Management
102

103
Controls the operational state of the scheduler instance.
104

105
```java { .api }
106
/**
107
 * Start the scheduler. Jobs will begin executing according to their triggers.
108
 * @throws SchedulerException if scheduler cannot be started
109
 */
110
void start() throws SchedulerException;
111

112
/**
113
 * Start the scheduler after the specified delay in seconds
114
 * @param seconds delay before starting the scheduler
115
 * @throws SchedulerException if scheduler cannot be started
116
 */
117
void startDelayed(int seconds) throws SchedulerException;
118

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

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

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

138
/**
139
 * Check if the scheduler has been started
140
 * @return true if scheduler is started and operational
141
 * @throws SchedulerException if scheduler state cannot be determined
142
 */
143
boolean isStarted() throws SchedulerException;
144

145
/**
146
 * Check if the scheduler is in standby mode
147
 * @return true if scheduler is in standby mode
148
 * @throws SchedulerException if scheduler state cannot be determined
149
 */
150
boolean isInStandbyMode() throws SchedulerException;
151

152
/**
153
 * Check if the scheduler has been shutdown
154
 * @return true if scheduler has been shutdown
155
 * @throws SchedulerException if scheduler state cannot be determined
156
 */
157
boolean isShutdown() throws SchedulerException;
158
```
159

160
**Usage Examples:**
161

162
```java
163
Scheduler scheduler = new StdSchedulerFactory().getScheduler();
164

165
// Start scheduler
166
scheduler.start();
167

168
// Check status
169
if (scheduler.isStarted()) {
170
    System.out.println("Scheduler is running");
171
}
172

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

176
// Resume from standby
177
scheduler.start();
178

179
// Shutdown gracefully
180
scheduler.shutdown(true); // Wait for jobs to complete
181
```
182

183
### Basic Job Scheduling
184

185
Core operations for scheduling jobs with triggers.
186

187
```java { .api }
188
/**
189
 * Schedule a job with an associated trigger
190
 * @param jobDetail the job to be scheduled
191
 * @param trigger the trigger that will fire the job
192
 * @return the date/time the job was first scheduled to run
193
 * @throws SchedulerException if job cannot be scheduled
194
 */
195
Date scheduleJob(JobDetail jobDetail, Trigger trigger) throws SchedulerException;
196

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

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

214
**Usage Examples:**
215

216
```java
217
// Basic job scheduling
218
JobDetail job = newJob(MyJob.class)
219
    .withIdentity("job1", "group1")
220
    .build();
221

222
Trigger trigger = newTrigger()
223
    .withIdentity("trigger1", "group1")
224
    .startNow()
225
    .withSchedule(simpleSchedule()
226
        .withIntervalInSeconds(30)
227
        .repeatForever())
228
    .build();
229

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

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

239
scheduler.scheduleJob(additionalTrigger);
240

241
// Batch scheduling
242
Map<JobDetail, Set<? extends Trigger>> jobsAndTriggers = new HashMap<>();
243
jobsAndTriggers.put(job1, Set.of(trigger1, trigger2));
244
jobsAndTriggers.put(job2, Set.of(trigger3));
245
scheduler.scheduleJobs(jobsAndTriggers, false);
246
```
247

248
### Advanced Scheduling Operations
249

250
Additional scheduling control methods for job and trigger management.
251

252
```java { .api }
253
/**
254
 * Add a job to the scheduler without scheduling it (durable job)
255
 * @param jobDetail the job to add
256
 * @param replace if true, replace existing job with same key
257
 * @throws SchedulerException if job cannot be added
258
 */
259
void addJob(JobDetail jobDetail, boolean replace) throws SchedulerException;
260

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

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

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

284
/**
285
 * Trigger a job execution with additional job data
286
 * @param jobKey the key identifying the job to trigger
287
 * @param data additional data to pass to the job
288
 * @throws SchedulerException if job cannot be triggered
289
 */
290
void triggerJob(JobKey jobKey, JobDataMap data) throws SchedulerException;
291
```
292

293
**Usage Examples:**
294

295
```java
296
// Add durable job (persists without triggers)
297
JobDetail durableJob = newJob(MaintenanceJob.class)
298
    .withIdentity("maintenance", "system")
299
    .storeDurably()
300
    .build();
301
scheduler.addJob(durableJob, false);
302

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

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

311
// Delete jobs
312
scheduler.deleteJob(jobKey("job1", "group1"));
313
scheduler.deleteJobs(List.of(
314
    jobKey("job1", "group1"),
315
    jobKey("job2", "group1")
316
));
317
```
318

319
### Scheduler Metadata and Context
320

321
Access scheduler information and application context.
322

323
```java { .api }
324
/**
325
 * Get metadata about this scheduler instance
326
 * @return scheduler metadata including version, status, capabilities
327
 * @throws SchedulerException if metadata cannot be retrieved
328
 */
329
SchedulerMetaData getMetaData() throws SchedulerException;
330

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

338
/**
339
 * Get the scheduler's unique name
340
 * @return scheduler instance name
341
 * @throws SchedulerException if name cannot be retrieved
342
 */
343
String getSchedulerName() throws SchedulerException;
344

345
/**
346
 * Get the scheduler's instance ID
347
 * @return scheduler instance identifier
348
 * @throws SchedulerException if instance ID cannot be retrieved
349
 */
350
String getSchedulerInstanceId() throws SchedulerException;
351
```
352

353
**Usage Examples:**
354

355
```java
356
// Get scheduler information
357
SchedulerMetaData metaData = scheduler.getMetaData();
358
System.out.println("Scheduler: " + metaData.getSchedulerName());
359
System.out.println("Version: " + metaData.getVersion());
360
System.out.println("Started: " + metaData.getRunningSince());
361

362
// Use scheduler context for shared data
363
SchedulerContext context = scheduler.getContext();
364
context.put("applicationVersion", "1.0.0");
365
context.put("configuration", appConfig);
366
```