0
# Trigger Management
1

2
Trigger creation, scheduling control, and various trigger types in Quartz. Triggers define when and how often jobs should be executed, supporting different scheduling patterns from simple intervals to complex cron expressions.
3

4
## Capabilities
5

6
### Trigger Interface
7

8
Base interface for all trigger types that defines scheduling behavior and timing control.
9

10
```java { .api }
11
/**
12
 * Base interface for all trigger types that control job execution timing
13
 */
14
interface Trigger extends Serializable, Cloneable, Comparable<Trigger> {
15
    /**
16
     * Wildcard for matching all groups
17
     */
18
    String DEFAULT_GROUP = "DEFAULT";
19
    
20
    /**
21
     * Smart misfire policy - let Quartz decide how to handle misfires
22
     */
23
    int MISFIRE_INSTRUCTION_SMART_POLICY = 0;
24
    
25
    /**
26
     * Ignore misfire policy - execute as if no misfire occurred
27
     */
28
    int MISFIRE_INSTRUCTION_IGNORE_MISFIRE_POLICY = -1;
29
    
30
    /**
31
     * Default trigger priority
32
     */
33
    int DEFAULT_PRIORITY = 5;
34
    
35
    /**
36
     * Possible states for a trigger
37
     */
38
    enum TriggerState {
39
        NONE, NORMAL, PAUSED, COMPLETE, ERROR, BLOCKED
40
    }
41
    
42
    /**
43
     * Instructions that can be returned by trigger completion
44
     */
45
    enum CompletedExecutionInstruction {
46
        NOOP, RE_EXECUTE_JOB, SET_TRIGGER_COMPLETE, DELETE_TRIGGER,
47
        SET_ALL_JOB_TRIGGERS_COMPLETE, SET_TRIGGER_ERROR, SET_ALL_JOB_TRIGGERS_ERROR
48
    }
49
    
50
    /**
51
     * Get the unique key that identifies this trigger
52
     * @return the trigger's key (name and group)
53
     */
54
    TriggerKey getKey();
55
    
56
    /**
57
     * Get the key of the job this trigger fires
58
     * @return the associated job's key
59
     */
60
    JobKey getJobKey();
61
    
62
    /**
63
     * Get the trigger's human-readable description
64
     * @return description or null if none set
65
     */
66
    String getDescription();
67
    
68
    /**
69
     * Get the name of the calendar modifying this trigger's schedule
70
     * @return calendar name or null if none associated
71
     */
72
    String getCalendarName();
73
    
74
    /**
75
     * Get the job data map for this trigger
76
     * @return trigger's job data map (never null)
77
     */
78
    JobDataMap getJobDataMap();
79
    
80
    /**
81
     * Get the trigger's priority for execution ordering
82
     * @return priority value (higher numbers = higher priority)
83
     */
84
    int getPriority();
85
    
86
    /**
87
     * Get the time this trigger should start firing
88
     * @return start time
89
     */
90
    Date getStartTime();
91
    
92
    /**
93
     * Get the time this trigger should stop firing
94
     * @return end time or null if no end time
95
     */
96
    Date getEndTime();
97
    
98
    /**
99
     * Get the next time this trigger will fire
100
     * @return next fire time or null if trigger won't fire again
101
     */
102
    Date getNextFireTime();
103
    
104
    /**
105
     * Get the previous time this trigger fired
106
     * @return previous fire time or null if never fired
107
     */
108
    Date getPreviousFireTime();
109
    
110
    /**
111
     * Get the next fire time after the given time
112
     * @param afterTime time to search after
113
     * @return next fire time after the given time
114
     */
115
    Date getFireTimeAfter(Date afterTime);
116
    
117
    /**
118
     * Get the final time this trigger will fire
119
     * @return final fire time or null if fires indefinitely
120
     */
121
    Date getFinalFireTime();
122
    
123
    /**
124
     * Get the misfire instruction for this trigger
125
     * @return misfire instruction code
126
     */
127
    int getMisfireInstruction();
128
    
129
    /**
130
     * Check if this trigger may fire again
131
     * @return true if trigger has remaining firings
132
     */
133
    boolean mayFireAgain();
134
    
135
    /**
136
     * Get a TriggerBuilder to create a similar trigger
137
     * @return builder configured like this trigger
138
     */
139
    TriggerBuilder<? extends Trigger> getTriggerBuilder();
140
    
141
    /**
142
     * Get a ScheduleBuilder to recreate this trigger's schedule
143
     * @return schedule builder for this trigger type
144
     */
145
    ScheduleBuilder<? extends Trigger> getScheduleBuilder();
146
}
147
```
148

149
### TriggerBuilder Class
150

151
Fluent builder for creating triggers with comprehensive configuration options.
152

153
```java { .api }
154
/**
155
 * Builder for Trigger instances using fluent interface
156
 */
157
class TriggerBuilder<T extends Trigger> {
158
    /**
159
     * Create a new TriggerBuilder
160
     * @return new builder instance
161
     */
162
    static TriggerBuilder<Trigger> newTrigger();
163
    
164
    /**
165
     * Set the trigger's identity using name only (uses DEFAULT_GROUP)
166
     * @param name the trigger name
167
     * @return this builder for method chaining
168
     */
169
    TriggerBuilder<T> withIdentity(String name);
170
    
171
    /**
172
     * Set the trigger's identity using name and group
173
     * @param name the trigger name
174
     * @param group the trigger group
175
     * @return this builder for method chaining
176
     */
177
    TriggerBuilder<T> withIdentity(String name, String group);
178
    
179
    /**
180
     * Set the trigger's identity using a TriggerKey
181
     * @param triggerKey the complete trigger key
182
     * @return this builder for method chaining
183
     */
184
    TriggerBuilder<T> withIdentity(TriggerKey triggerKey);
185
    
186
    /**
187
     * Set the trigger's description
188
     * @param triggerDescription human-readable description
189
     * @return this builder for method chaining
190
     */
191
    TriggerBuilder<T> withDescription(String triggerDescription);
192
    
193
    /**
194
     * Set the trigger's priority (default is 5)
195
     * @param triggerPriority priority value (higher = more important)
196
     * @return this builder for method chaining
197
     */
198
    TriggerBuilder<T> withPriority(int triggerPriority);
199
    
200
    /**
201
     * Associate a calendar with this trigger
202
     * @param calName name of calendar to modify trigger schedule
203
     * @return this builder for method chaining
204
     */
205
    TriggerBuilder<T> modifiedByCalendar(String calName);
206
    
207
    /**
208
     * Set the trigger start time
209
     * @param triggerStartTime when the trigger should start firing
210
     * @return this builder for method chaining
211
     */
212
    TriggerBuilder<T> startAt(Date triggerStartTime);
213
    
214
    /**
215
     * Set the trigger to start immediately
216
     * @return this builder for method chaining
217
     */
218
    TriggerBuilder<T> startNow();
219
    
220
    /**
221
     * Set the trigger end time
222
     * @param triggerEndTime when the trigger should stop firing
223
     * @return this builder for method chaining
224
     */
225
    TriggerBuilder<T> endAt(Date triggerEndTime);
226
    
227
    /**
228
     * Set the trigger's schedule using a ScheduleBuilder
229
     * @param schedBuilder the schedule builder defining firing pattern
230
     * @return typed builder for the schedule type
231
     */
232
    <SBT extends T> TriggerBuilder<SBT> withSchedule(ScheduleBuilder<SBT> schedBuilder);
233
    
234
    /**
235
     * Associate trigger with a job using JobKey
236
     * @param keyOfJobToFire the job key
237
     * @return this builder for method chaining
238
     */
239
    TriggerBuilder<T> forJob(JobKey keyOfJobToFire);
240
    
241
    /**
242
     * Associate trigger with a job using name (DEFAULT_GROUP)
243
     * @param jobName the job name
244
     * @return this builder for method chaining
245
     */
246
    TriggerBuilder<T> forJob(String jobName);
247
    
248
    /**
249
     * Associate trigger with a job using name and group
250
     * @param jobName the job name
251
     * @param jobGroup the job group
252
     * @return this builder for method chaining
253
     */
254
    TriggerBuilder<T> forJob(String jobName, String jobGroup);
255
    
256
    /**
257
     * Associate trigger with a job using JobDetail
258
     * @param jobDetail the job detail
259
     * @return this builder for method chaining
260
     */
261
    TriggerBuilder<T> forJob(JobDetail jobDetail);
262
    
263
    /**
264
     * Add data to the trigger's job data map
265
     * @param key the data key
266
     * @param value the data value
267
     * @return this builder for method chaining
268
     */
269
    TriggerBuilder<T> usingJobData(String key, String value);
270
    
271
    /**
272
     * Add integer data to the trigger's job data map
273
     * @param key the data key
274
     * @param value the integer value
275
     * @return this builder for method chaining
276
     */
277
    TriggerBuilder<T> usingJobData(String key, Integer value);
278
    
279
    /**
280
     * Add long data to the trigger's job data map
281
     * @param key the data key
282
     * @param value the long value
283
     * @return this builder for method chaining
284
     */
285
    TriggerBuilder<T> usingJobData(String key, Long value);
286
    
287
    /**
288
     * Add float data to the trigger's job data map
289
     * @param key the data key
290
     * @param value the float value
291
     * @return this builder for method chaining
292
     */
293
    TriggerBuilder<T> usingJobData(String key, Float value);
294
    
295
    /**
296
     * Add double data to the trigger's job data map
297
     * @param key the data key
298
     * @param value the double value
299
     * @return this builder for method chaining
300
     */
301
    TriggerBuilder<T> usingJobData(String key, Double value);
302
    
303
    /**
304
     * Add boolean data to the trigger's job data map
305
     * @param key the data key
306
     * @param value the boolean value
307
     * @return this builder for method chaining
308
     */
309
    TriggerBuilder<T> usingJobData(String key, Boolean value);
310
    
311
    /**
312
     * Set the trigger's entire job data map
313
     * @param newJobDataMap the job data map
314
     * @return this builder for method chaining
315
     */
316
    TriggerBuilder<T> usingJobData(JobDataMap newJobDataMap);
317
    
318
    /**
319
     * Build the trigger instance
320
     * @return the configured trigger
321
     */
322
    T build();
323
}
324
```
325

326
**Usage Examples:**
327

328
```java
329
// Basic trigger creation
330
Trigger simpleTrigger = newTrigger()
331
    .withIdentity("trigger1", "group1")
332
    .withDescription("Daily report trigger")
333
    .startNow()
334
    .withSchedule(simpleSchedule()
335
        .withIntervalInMinutes(60)
336
        .repeatForever())
337
    .forJob("reportJob", "group1")
338
    .build();
339

340
// Trigger with advanced configuration
341
Trigger complexTrigger = newTrigger()
342
    .withIdentity("complexTrigger", "processing")
343
    .withDescription("Complex processing trigger")
344
    .withPriority(10) // High priority
345
    .startAt(DateBuilder.futureDate(5, DateBuilder.IntervalUnit.MINUTE))
346
    .endAt(DateBuilder.futureDate(1, DateBuilder.IntervalUnit.HOUR))
347
    .modifiedByCalendar("businessHours")
348
    .usingJobData("mode", "batch")
349
    .usingJobData("maxRecords", 1000)
350
    .usingJobData("retryEnabled", true)
351
    .forJob(jobKey("dataProcessor", "processing"))
352
    .withSchedule(cronSchedule("0 */15 9-17 * * MON-FRI"))
353
    .build();
354

355
// Static imports for cleaner syntax
356
import static org.quartz.TriggerBuilder.*;
357
import static org.quartz.SimpleScheduleBuilder.*;
358
import static org.quartz.CronScheduleBuilder.*;
359

360
Trigger cleanTrigger = newTrigger()
361
    .withIdentity("myTrigger")
362
    .forJob("myJob")
363
    .withSchedule(repeatSecondlyForever(30))
364
    .build();
365
```
366

367
### TriggerKey Class
368

369
Unique identifier for trigger instances combining name and group.
370

371
```java { .api }
372
/**
373
 * Uniquely identifies a Trigger within a Scheduler
374
 */
375
class TriggerKey extends Key<TriggerKey> {
376
    /**
377
     * Create a TriggerKey with name in the default group
378
     * @param name the trigger name
379
     */
380
    TriggerKey(String name);
381
    
382
    /**
383
     * Create a TriggerKey with name and group
384
     * @param name the trigger name
385
     * @param group the trigger group
386
     */
387
    TriggerKey(String name, String group);
388
    
389
    /**
390
     * Static factory method for TriggerKey with default group
391
     * @param name the trigger name
392
     * @return new TriggerKey instance
393
     */
394
    static TriggerKey triggerKey(String name);
395
    
396
    /**
397
     * Static factory method for TriggerKey with group
398
     * @param name the trigger name
399
     * @param group the trigger group
400
     * @return new TriggerKey instance
401
     */
402
    static TriggerKey triggerKey(String name, String group);
403
}
404
```
405

406
### Trigger State Management
407

408
Methods for controlling trigger execution state through the Scheduler interface.
409

410
```java { .api }
411
/**
412
 * Remove a trigger from the scheduler
413
 * @param triggerKey the trigger to remove
414
 * @return true if trigger was found and removed
415
 * @throws SchedulerException if trigger cannot be removed
416
 */
417
boolean unscheduleJob(TriggerKey triggerKey) throws SchedulerException;
418

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

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

436
/**
437
 * Pause a specific trigger
438
 * @param triggerKey the trigger to pause
439
 * @throws SchedulerException if trigger cannot be paused
440
 */
441
void pauseTrigger(TriggerKey triggerKey) throws SchedulerException;
442

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

450
/**
451
 * Resume a specific trigger
452
 * @param triggerKey the trigger to resume
453
 * @throws SchedulerException if trigger cannot be resumed
454
 */
455
void resumeTrigger(TriggerKey triggerKey) throws SchedulerException;
456

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

464
/**
465
 * Get the current state of a trigger
466
 * @param triggerKey the trigger to check
467
 * @return the trigger's current state
468
 * @throws SchedulerException if trigger state cannot be determined
469
 */
470
TriggerState getTriggerState(TriggerKey triggerKey) throws SchedulerException;
471

472
/**
473
 * Get trigger details
474
 * @param triggerKey the trigger to retrieve
475
 * @return the trigger instance or null if not found
476
 * @throws SchedulerException if trigger cannot be retrieved
477
 */
478
Trigger getTrigger(TriggerKey triggerKey) throws SchedulerException;
479
```
480

481
**Usage Examples:**
482

483
```java
484
// Trigger state management
485
TriggerKey triggerKey = triggerKey("myTrigger", "myGroup");
486

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

493
// Pause trigger
494
scheduler.pauseTrigger(triggerKey);
495

496
// Resume trigger
497
scheduler.resumeTrigger(triggerKey);
498

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

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

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

511
// Group operations using matchers
512
scheduler.pauseTriggers(GroupMatcher.groupEquals("reports"));
513
scheduler.resumeTriggers(GroupMatcher.groupStartsWith("batch"));
514
```
515

516
### SimpleTrigger Interface
517

518
Simple interval-based trigger for regular repetition patterns.
519

520
```java { .api }
521
/**
522
 * Trigger that fires at regular intervals
523
 */
524
interface SimpleTrigger extends Trigger {
525
    /**
526
     * Constant for unlimited repeats
527
     */
528
    int REPEAT_INDEFINITELY = -1;
529
    
530
    // Misfire instruction constants
531
    int MISFIRE_INSTRUCTION_FIRE_NOW = 1;
532
    int MISFIRE_INSTRUCTION_RESCHEDULE_NOW_WITH_EXISTING_REPEAT_COUNT = 2;
533
    int MISFIRE_INSTRUCTION_RESCHEDULE_NOW_WITH_REMAINING_REPEAT_COUNT = 3;
534
    int MISFIRE_INSTRUCTION_RESCHEDULE_NEXT_WITH_REMAINING_COUNT = 4;
535
    int MISFIRE_INSTRUCTION_RESCHEDULE_NEXT_WITH_EXISTING_COUNT = 5;
536
    
537
    /**
538
     * Get the number of times the trigger should repeat
539
     * @return repeat count or REPEAT_INDEFINITELY
540
     */
541
    int getRepeatCount();
542
    
543
    /**
544
     * Get the interval between firings
545
     * @return interval in milliseconds
546
     */
547
    long getRepeatInterval();
548
    
549
    /**
550
     * Get the number of times this trigger has fired
551
     * @return times triggered count
552
     */
553
    int getTimesTriggered();
554
}
555
```
556

557
### CronTrigger Interface
558

559
Cron expression-based trigger for complex scheduling patterns.
560

561
```java { .api }
562
/**
563
 * Trigger that fires based on cron expressions
564
 */
565
interface CronTrigger extends Trigger {
566
    // Misfire instruction constants
567
    int MISFIRE_INSTRUCTION_FIRE_ONCE_NOW = 1;
568
    int MISFIRE_INSTRUCTION_DO_NOTHING = 2;
569
    
570
    /**
571
     * Get the cron expression string
572
     * @return the cron expression
573
     */
574
    String getCronExpression();
575
    
576
    /**
577
     * Get the time zone for cron expression evaluation
578
     * @return the time zone
579
     */
580
    TimeZone getTimeZone();
581
    
582
    /**
583
     * Get the expression summary for display
584
     * @return human-readable description of the cron expression
585
     */
586
    String getExpressionSummary();
587
}
588
```
589

590
### CalendarIntervalTrigger Interface
591

592
Calendar-based interval trigger for date-aware scheduling.
593

594
```java { .api }
595
/**
596
 * Trigger that fires at calendar-based intervals
597
 */
598
interface CalendarIntervalTrigger extends Trigger {
599
    // Misfire instruction constants
600
    int MISFIRE_INSTRUCTION_FIRE_ONCE_NOW = 1;
601
    int MISFIRE_INSTRUCTION_DO_NOTHING = 2;
602
    
603
    /**
604
     * Get the repeat interval unit
605
     * @return the calendar interval unit
606
     */
607
    DateBuilder.IntervalUnit getRepeatIntervalUnit();
608
    
609
    /**
610
     * Get the repeat interval value
611
     * @return the interval value
612
     */
613
    int getRepeatInterval();
614
    
615
    /**
616
     * Get the number of times this trigger has fired
617
     * @return times triggered count
618
     */
619
    int getTimesTriggered();
620
    
621
    /**
622
     * Check if time zone should be preserved across DST changes
623
     * @return true if time zone is preserved
624
     */
625
    boolean isPreserveHourOfDayAcrossDaylightSavings();
626
    
627
    /**
628
     * Check if intervals should skip days when DST changes occur
629
     * @return true if DST days are skipped
630
     */
631
    boolean isSkipDayIfHourDoesNotExist();
632
}
633
```
634

635
### DailyTimeIntervalTrigger Interface
636

637
Daily time interval trigger for firing during specific time periods.
638

639
```java { .api }
640
/**
641
 * Trigger that fires at intervals during specific days and times
642
 */
643
interface DailyTimeIntervalTrigger extends Trigger {
644
    // Misfire instruction constants
645
    int MISFIRE_INSTRUCTION_FIRE_ONCE_NOW = 1;
646
    int MISFIRE_INSTRUCTION_DO_NOTHING = 2;
647
    
648
    /**
649
     * Get the days of week this trigger fires
650
     * @return set of day numbers (1=Sunday, 7=Saturday)
651
     */
652
    Set<Integer> getDaysOfWeek();
653
    
654
    /**
655
     * Get the start time of day
656
     * @return start time
657
     */
658
    TimeOfDay getStartTimeOfDay();
659
    
660
    /**
661
     * Get the end time of day
662
     * @return end time
663
     */
664
    TimeOfDay getEndTimeOfDay();
665
    
666
    /**
667
     * Get the repeat interval
668
     * @return interval value
669
     */
670
    int getRepeatInterval();
671
    
672
    /**
673
     * Get the repeat interval unit
674
     * @return interval unit (SECOND, MINUTE, HOUR)
675
     */
676
    DateBuilder.IntervalUnit getRepeatIntervalUnit();
677
    
678
    /**
679
     * Get the number of times this trigger has fired
680
     * @return times triggered count
681
     */
682
    int getTimesTriggered();
683
}
684
```
685

686
**Usage Examples:**
687

688
```java
689
// Query trigger information
690
SimpleTrigger simple = (SimpleTrigger) scheduler.getTrigger(triggerKey("simple1"));
691
System.out.println("Repeat count: " + simple.getRepeatCount());
692
System.out.println("Interval: " + simple.getRepeatInterval() + "ms");
693
System.out.println("Times fired: " + simple.getTimesTriggered());
694

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

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

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