0
# Matcher Framework
1

2
Advanced pattern matching system for selecting jobs and triggers in Quartz based on various criteria. Matchers provide flexible, type-safe selection mechanisms for bulk operations on jobs and triggers, supporting complex filtering and group operations.
3

4
## Capabilities
5

6
### Matcher Interface
7

8
Base interface for all matcher implementations that define selection criteria.
9

10
```java { .api }
11
/**
12
 * Interface for matching jobs and triggers based on criteria
13
 * @param <T> the type being matched (JobKey or TriggerKey)
14
 */
15
interface Matcher<T extends Key<T>> extends Serializable {
16
    /**
17
     * Determine if the given key matches this matcher's criteria
18
     * @param key the key to test
19
     * @return true if the key matches
20
     */
21
    boolean isMatch(T key);
22
}
23
```
24

25
### GroupMatcher Class
26

27
Matcher for selecting keys based on group patterns.
28

29
```java { .api }
30
/**
31
 * Matcher that matches keys based on group patterns
32
 * @param <T> the key type (JobKey or TriggerKey)
33
 */
34
class GroupMatcher<T extends Key<T>> implements Matcher<T> {
35
    /**
36
     * Create matcher for exact group name
37
     * @param group the exact group name to match
38
     * @return GroupMatcher for the group
39
     */
40
    static <T extends Key<T>> GroupMatcher<T> groupEquals(String group);
41
    
42
    /**
43
     * Create matcher for groups starting with prefix
44
     * @param groupPrefix the group prefix to match
45
     * @return GroupMatcher for the prefix
46
     */
47
    static <T extends Key<T>> GroupMatcher<T> groupStartsWith(String groupPrefix);
48
    
49
    /**
50
     * Create matcher for groups ending with suffix
51
     * @param groupSuffix the group suffix to match
52
     * @return GroupMatcher for the suffix
53
     */
54
    static <T extends Key<T>> GroupMatcher<T> groupEndsWith(String groupSuffix);
55
    
56
    /**
57
     * Create matcher for groups containing substring
58
     * @param groupContains the substring that groups must contain
59
     * @return GroupMatcher for the substring
60
     */
61
    static <T extends Key<T>> GroupMatcher<T> groupContains(String groupContains);
62
    
63
    /**
64
     * Create matcher for any group (matches all)
65
     * @return GroupMatcher that matches any group
66
     */
67
    static <T extends Key<T>> GroupMatcher<T> anyGroup();
68
    
69
    /**
70
     * Create matcher for jobs in any of the specified groups
71
     * @return GroupMatcher for job groups
72
     */
73
    static GroupMatcher<JobKey> anyJobGroup();
74
    
75
    /**
76
     * Create matcher for triggers in any of the specified groups
77
     * @return GroupMatcher for trigger groups
78
     */
79
    static GroupMatcher<TriggerKey> anyTriggerGroup();
80
    
81
    /**
82
     * Create matcher for specific job group
83
     * @param group the job group name
84
     * @return GroupMatcher for the job group
85
     */
86
    static GroupMatcher<JobKey> jobGroupEquals(String group);
87
    
88
    /**
89
     * Create matcher for specific trigger group
90
     * @param group the trigger group name
91
     * @return GroupMatcher for the trigger group
92
     */
93
    static GroupMatcher<TriggerKey> triggerGroupEquals(String group);
94
    
95
    /**
96
     * Create matcher for job groups starting with prefix
97
     * @param groupPrefix the job group prefix
98
     * @return GroupMatcher for the job group prefix
99
     */
100
    static GroupMatcher<JobKey> jobGroupStartsWith(String groupPrefix);
101
    
102
    /**
103
     * Create matcher for trigger groups starting with prefix
104
     * @param groupPrefix the trigger group prefix
105
     * @return GroupMatcher for the trigger group prefix
106
     */
107
    static GroupMatcher<TriggerKey> triggerGroupStartsWith(String groupPrefix);
108
    
109
    /**
110
     * Create matcher for job groups ending with suffix
111
     * @param groupSuffix the job group suffix
112
     * @return GroupMatcher for the job group suffix
113
     */
114
    static GroupMatcher<JobKey> jobGroupEndsWith(String groupSuffix);
115
    
116
    /**
117
     * Create matcher for trigger groups ending with suffix
118
     * @param groupSuffix the trigger group suffix
119
     * @return GroupMatcher for the trigger group suffix
120
     */
121
    static GroupMatcher<TriggerKey> triggerGroupEndsWith(String groupSuffix);
122
    
123
    /**
124
     * Create matcher for job groups containing substring
125
     * @param groupContains the substring for job groups
126
     * @return GroupMatcher for job groups containing substring
127
     */
128
    static GroupMatcher<JobKey> jobGroupContains(String groupContains);
129
    
130
    /**
131
     * Create matcher for trigger groups containing substring
132
     * @param groupContains the substring for trigger groups
133
     * @return GroupMatcher for trigger groups containing substring
134
     */
135
    static GroupMatcher<TriggerKey> triggerGroupContains(String groupContains);
136
}
137
```
138

139
### NameMatcher Class
140

141
Matcher for selecting keys based on name patterns.
142

143
```java { .api }
144
/**
145
 * Matcher that matches keys based on name patterns
146
 * @param <T> the key type (JobKey or TriggerKey)
147
 */
148
class NameMatcher<T extends Key<T>> implements Matcher<T> {
149
    /**
150
     * Create matcher for exact name
151
     * @param name the exact name to match
152
     * @return NameMatcher for the name
153
     */
154
    static <T extends Key<T>> NameMatcher<T> nameEquals(String name);
155
    
156
    /**
157
     * Create matcher for names starting with prefix
158
     * @param namePrefix the name prefix to match
159
     * @return NameMatcher for the prefix
160
     */
161
    static <T extends Key<T>> NameMatcher<T> nameStartsWith(String namePrefix);
162
    
163
    /**
164
     * Create matcher for names ending with suffix
165
     * @param nameSuffix the name suffix to match
166
     * @return NameMatcher for the suffix
167
     */
168
    static <T extends Key<T>> NameMatcher<T> nameEndsWith(String nameSuffix);
169
    
170
    /**
171
     * Create matcher for names containing substring
172
     * @param nameContains the substring that names must contain
173
     * @return NameMatcher for the substring
174
     */
175
    static <T extends Key<T>> NameMatcher<T> nameContains(String nameContains);
176
}
177
```
178

179
### KeyMatcher Class
180

181
Matcher for selecting specific keys.
182

183
```java { .api }
184
/**
185
 * Matcher that matches specific keys
186
 * @param <T> the key type (JobKey or TriggerKey)
187
 */
188
class KeyMatcher<T extends Key<T>> implements Matcher<T> {
189
    /**
190
     * Create matcher for a specific key
191
     * @param key the key to match
192
     * @return KeyMatcher for the key
193
     */
194
    static <T extends Key<T>> KeyMatcher<T> keyEquals(T key);
195
}
196
```
197

198
### EverythingMatcher Class
199

200
Matcher that matches all keys.
201

202
```java { .api }
203
/**
204
 * Matcher that matches everything
205
 * @param <T> the key type (JobKey or TriggerKey)
206
 */
207
class EverythingMatcher<T extends Key<T>> implements Matcher<T> {
208
    /**
209
     * Create matcher that matches all keys
210
     * @return EverythingMatcher instance
211
     */
212
    static <T extends Key<T>> EverythingMatcher<T> allJobs();
213
    static <T extends Key<T>> EverythingMatcher<T> allTriggers();
214
}
215
```
216

217
### AndMatcher Class
218

219
Matcher that combines multiple matchers with logical AND.
220

221
```java { .api }
222
/**
223
 * Matcher that performs logical AND of multiple matchers
224
 * @param <T> the key type (JobKey or TriggerKey)
225
 */
226
class AndMatcher<T extends Key<T>> implements Matcher<T> {
227
    /**
228
     * Create AND matcher from multiple matchers
229
     * @param matchers the matchers to combine with AND
230
     * @return AndMatcher combining all matchers
231
     */
232
    @SafeVarargs
233
    static <T extends Key<T>> AndMatcher<T> and(Matcher<T>... matchers);
234
    
235
    /**
236
     * Create AND matcher from list of matchers
237
     * @param matchers the list of matchers to combine
238
     * @return AndMatcher combining all matchers
239
     */
240
    static <T extends Key<T>> AndMatcher<T> and(List<Matcher<T>> matchers);
241
}
242
```
243

244
### OrMatcher Class
245

246
Matcher that combines multiple matchers with logical OR.
247

248
```java { .api }
249
/**
250
 * Matcher that performs logical OR of multiple matchers
251
 * @param <T> the key type (JobKey or TriggerKey)
252
 */
253
class OrMatcher<T extends Key<T>> implements Matcher<T> {
254
    /**
255
     * Create OR matcher from multiple matchers
256
     * @param matchers the matchers to combine with OR
257
     * @return OrMatcher combining all matchers
258
     */
259
    @SafeVarargs
260
    static <T extends Key<T>> OrMatcher<T> or(Matcher<T>... matchers);
261
    
262
    /**
263
     * Create OR matcher from list of matchers
264
     * @param matchers the list of matchers to combine
265
     * @return OrMatcher combining all matchers
266
     */
267
    static <T extends Key<T>> OrMatcher<T> or(List<Matcher<T>> matchers);
268
}
269
```
270

271
### NotMatcher Class
272

273
Matcher that negates another matcher.
274

275
```java { .api }
276
/**
277
 * Matcher that performs logical NOT of another matcher
278
 * @param <T> the key type (JobKey or TriggerKey)
279
 */
280
class NotMatcher<T extends Key<T>> implements Matcher<T> {
281
    /**
282
     * Create NOT matcher that negates another matcher
283
     * @param matcher the matcher to negate
284
     * @return NotMatcher that negates the given matcher
285
     */
286
    static <T extends Key<T>> NotMatcher<T> not(Matcher<T> matcher);
287
}
288
```
289

290
### StringMatcher Class
291

292
Advanced string pattern matcher with various comparison operations.
293

294
```java { .api }
295
/**
296
 * Utility for advanced string pattern matching
297
 */
298
class StringMatcher implements Serializable {
299
    /**
300
     * String comparison operations
301
     */
302
    enum StringOperatorName {
303
        EQUALS, STARTS_WITH, ENDS_WITH, CONTAINS, ANYTHING
304
    }
305
    
306
    /**
307
     * Create string matcher with operation
308
     * @param value the value to compare against
309
     * @param operation the comparison operation
310
     * @return StringMatcher instance
311
     */
312
    static StringMatcher stringMatcher(String value, StringOperatorName operation);
313
    
314
    /**
315
     * Create exact match string matcher
316
     * @param value the exact value to match
317
     * @return StringMatcher for exact match
318
     */
319
    static StringMatcher equals(String value);
320
    
321
    /**
322
     * Create starts-with string matcher
323
     * @param prefix the prefix to match
324
     * @return StringMatcher for starts-with
325
     */
326
    static StringMatcher startsWith(String prefix);
327
    
328
    /**
329
     * Create ends-with string matcher
330
     * @param suffix the suffix to match
331
     * @return StringMatcher for ends-with
332
     */
333
    static StringMatcher endsWith(String suffix);
334
    
335
    /**
336
     * Create contains string matcher
337
     * @param substring the substring to match
338
     * @return StringMatcher for contains
339
     */
340
    static StringMatcher contains(String substring);
341
    
342
    /**
343
     * Create matcher that matches anything
344
     * @return StringMatcher that matches any string
345
     */
346
    static StringMatcher anything();
347
    
348
    /**
349
     * Test if a value matches this matcher
350
     * @param value the value to test
351
     * @return true if the value matches
352
     */
353
    boolean compare(String value);
354
}
355
```
356

357
**Usage Examples:**
358

359
```java
360
import org.quartz.*;
361
import org.quartz.impl.matchers.*;
362
import static org.quartz.impl.matchers.GroupMatcher.*;
363
import static org.quartz.impl.matchers.NameMatcher.*;
364
import static org.quartz.impl.matchers.KeyMatcher.*;
365

366
// Group-based matching
367
Matcher<JobKey> reportJobs = jobGroupEquals("reports");
368
scheduler.pauseJobs(reportJobs);
369

370
Matcher<TriggerKey> batchTriggers = triggerGroupStartsWith("batch");
371
scheduler.pauseTriggers(batchTriggers);
372

373
// Name-based matching
374
Matcher<JobKey> importJobs = nameStartsWith("import");
375
scheduler.deleteJobs(scheduler.getJobKeys(importJobs));
376

377
Matcher<TriggerKey> dailyTriggers = nameEndsWith("Daily");
378
for (TriggerKey key : scheduler.getTriggerKeys(dailyTriggers)) {
379
    System.out.println("Daily trigger: " + key);
380
}
381

382
// Specific key matching
383
JobKey specificJob = jobKey("myJob", "myGroup");
384
Matcher<JobKey> specificMatcher = keyEquals(specificJob);
385
if (scheduler.checkExists(specificJob)) {
386
    scheduler.pauseJobs(specificMatcher);
387
}
388

389
// Logical combinations - pause all report jobs except monthly reports
390
Matcher<JobKey> allReports = jobGroupEquals("reports");
391
Matcher<JobKey> monthlyReports = nameContains("monthly");
392
Matcher<JobKey> nonMonthlyReports = and(allReports, not(monthlyReports));
393
scheduler.pauseJobs(nonMonthlyReports);
394

395
// Complex matching - all batch jobs or any trigger in maintenance group
396
Matcher<JobKey> batchJobMatcher = jobGroupEquals("batch");
397
Matcher<TriggerKey> maintenanceTriggerMatcher = triggerGroupEquals("maintenance");
398

399
// Pause batch jobs
400
scheduler.pauseJobs(batchJobMatcher);
401
// Pause maintenance triggers
402
scheduler.pauseTriggers(maintenanceTriggerMatcher);
403

404
// Multiple group operations
405
Matcher<JobKey> importOrExportJobs = or(
406
    jobGroupEquals("import"),
407
    jobGroupEquals("export")
408
);
409
scheduler.resumeJobs(importOrExportJobs);
410

411
// Pattern matching for cleanup - delete all temporary jobs
412
Matcher<JobKey> tempJobs = and(
413
    nameStartsWith("temp_"),
414
    jobGroupContains("cleanup")
415
);
416

417
List<JobKey> tempJobKeys = new ArrayList<>(scheduler.getJobKeys(tempJobs));
418
for (JobKey key : tempJobKeys) {
419
    scheduler.deleteJob(key);
420
}
421

422
// Advanced string matching for trigger management
423
Matcher<TriggerKey> hourlyTriggers = new Matcher<TriggerKey>() {
424
    @Override
425
    public boolean isMatch(TriggerKey key) {
426
        return key.getName().matches(".*[Hh]ourly.*");
427
    }
428
};
429

430
// Get all triggers and filter
431
Set<TriggerKey> allTriggers = scheduler.getTriggerKeys(GroupMatcher.anyTriggerGroup());
432
for (TriggerKey key : allTriggers) {
433
    if (hourlyTriggers.isMatch(key)) {
434
        Trigger trigger = scheduler.getTrigger(key);
435
        System.out.println("Hourly trigger: " + key + " next fire: " + trigger.getNextFireTime());
436
    }
437
}
438

439
// Utility methods with matchers
440
public void pauseJobsWithPrefix(Scheduler scheduler, String prefix) throws SchedulerException {
441
    Matcher<JobKey> matcher = nameStartsWith(prefix);
442
    scheduler.pauseJobs(matcher);
443
}
444

445
public void deleteTriggersInGroups(Scheduler scheduler, String... groups) throws SchedulerException {
446
    List<Matcher<TriggerKey>> matchers = new ArrayList<>();
447
    for (String group : groups) {
448
        matchers.add(triggerGroupEquals(group));
449
    }
450
    Matcher<TriggerKey> combinedMatcher = or(matchers);
451
    
452
    Set<TriggerKey> keys = scheduler.getTriggerKeys(combinedMatcher);
453
    for (TriggerKey key : keys) {
454
        scheduler.unscheduleJob(key);
455
    }
456
}
457
```
458

459
## Static Import Usage
460

461
For cleaner syntax, use static imports:
462

463
```java
464
import static org.quartz.impl.matchers.GroupMatcher.*;
465
import static org.quartz.impl.matchers.NameMatcher.*;
466
import static org.quartz.impl.matchers.KeyMatcher.*;
467
import static org.quartz.impl.matchers.EverythingMatcher.*;
468

469
// Much cleaner syntax
470
scheduler.pauseJobs(jobGroupEquals("reports"));
471
scheduler.pauseTriggers(triggerGroupStartsWith("batch"));
472
scheduler.resumeJobs(nameContains("import"));
473
scheduler.deleteJobs(and(jobGroupEquals("temp"), nameStartsWith("old_")));
474
```