0
# Processors
1

2
Processors contain the core build-time logic for CDI container construction, bean discovery, validation, and optimization. They implement @BuildStep methods that consume and produce build items to orchestrate the CDI build process.
3

4
## Capabilities
5

6
### Main ArC Processor
7

8
The central processor coordinating all aspects of CDI container build-time processing.
9

10
```java { .api }
11
/**
12
 * Main ArC processor with CDI build steps
13
 */
14
public class ArcProcessor {
15
    /**
16
     * Core build step that creates the final CDI bean container
17
     */
18
    @BuildStep
19
    public BeanContainerBuildItem build(
20
        ArcConfig config,
21
        BeanArchiveIndexBuildItem beanArchiveIndex,
22
        List<AdditionalBeanBuildItem> additionalBeans,
23
        List<SyntheticBeanBuildItem> syntheticBeans,
24
        List<UnremovableBeanBuildItem> unremovableBeans,
25
        List<BeanContainerListenerBuildItem> containerListeners
26
    );
27
    
28
    /**
29
     * Bean discovery and registration build step
30
     */
31
    @BuildStep  
32
    public BeanRegistrationPhaseBuildItem registerBeans(
33
        BeanArchiveIndexBuildItem beanArchiveIndex,
34
        List<AdditionalBeanBuildItem> additionalBeans,
35
        List<BeanDefiningAnnotationBuildItem> beanDefiningAnnotations
36
    );
37
    
38
    /**
39
     * Validation phase build step
40
     */
41
    @BuildStep
42
    public ValidationPhaseBuildItem validate(
43
        BeanRegistrationPhaseBuildItem beanRegistration,
44
        List<ValidationPhaseBuildItem.ValidationErrorBuildItem> validationErrors
45
    );
46
    
47
    /**
48
     * Context optimization build step
49
     */
50
    @BuildStep
51
    public void optimizeContexts(
52
        ArcConfig config,
53
        BuildProducer<OptimizedContextBuildItem> optimizedContexts
54
    );
55
    
56
    /**
57
     * Unused bean removal build step
58
     */
59
    @BuildStep
60
    public void removeUnusedBeans(
61
        ArcConfig config,
62
        BeanArchiveIndexBuildItem beanArchiveIndex,
63
        List<UnremovableBeanBuildItem> unremovableBeans,
64
        BuildProducer<RemovedBeanBuildItem> removedBeans
65
    );
66
}
67
```
68

69
**Usage Examples:**
70

71
```java
72
// Custom processor extending ArC functionality
73
public class MyArcExtensionProcessor {
74
    
75
    @BuildStep
76
    AdditionalBeanBuildItem addCustomBeans() {
77
        return AdditionalBeanBuildItem.builder()
78
            .addBeanClasses(MyCustomService.class)
79
            .setUnremovable()
80
            .build();
81
    }
82
    
83
    @BuildStep  
84
    UnremovableBeanBuildItem protectFrameworkBeans() {
85
        return UnremovableBeanBuildItem.beanClassAnnotation(
86
            DotName.createSimple("com.example.FrameworkComponent")
87
        );
88
    }
89
    
90
    @BuildStep
91
    @Record(ExecutionTime.RUNTIME_INIT)
92
    void configureRuntime(BeanContainerBuildItem beanContainer,
93
                         MyRecorder recorder) {
94
        recorder.initialize(beanContainer.getValue());
95
    }
96
}
97
```
98

99
### Synthetic Bean Processor
100

101
Specialized processor for handling synthetic (programmatically created) beans.
102

103
```java { .api }
104
/**
105
 * Processor for synthetic bean creation and management
106
 */
107
public class SyntheticBeansProcessor {
108
    /**
109
     * Process synthetic bean build items and create bean definitions
110
     */
111
    @BuildStep
112
    public void processSyntheticBeans(
113
        List<SyntheticBeanBuildItem> syntheticBeans,
114
        BuildProducer<GeneratedBeanBuildItem> generatedBeans
115
    );
116
    
117
    /**
118
     * Initialize synthetic beans at runtime
119
     */
120
    @BuildStep
121
    @Record(ExecutionTime.RUNTIME_INIT)
122
    public SyntheticBeansRuntimeInitBuildItem initializeSyntheticBeans(
123
        List<SyntheticBeanBuildItem> syntheticBeans,
124
        SyntheticBeansRecorder recorder
125
    );
126
}
127
```
128

129
### Bean Archive Processor
130

131
Handles bean archive discovery, indexing, and Jandex integration.
132

133
```java { .api }
134
/**
135
 * Processor for bean archive discovery and indexing
136
 */
137
public class BeanArchiveProcessor {
138
    /**
139
     * Build the bean archive index from discovered classes
140
     */
141
    @BuildStep
142
    public BeanArchiveIndexBuildItem buildBeanArchiveIndex(
143
        CombinedIndexBuildItem combinedIndex,
144
        List<BeanArchivePredicateBuildItem> beanArchivePredicates,
145
        List<AdditionalBeanBuildItem> additionalBeans
146
    );
147
    
148
    /**
149
     * Discover bean archives from the application classpath
150
     */
151
    @BuildStep
152
    public void discoverBeanArchives(
153
        ApplicationArchivesBuildItem archives,
154
        BuildProducer<BeanArchivePredicateBuildItem> beanArchivePredicates
155
    );
156
}
157
```
158

159
### Auto-Scoping Processor
160

161
Automatically adds scope annotations to classes based on configured rules.
162

163
```java { .api }
164
/**
165
 * Processor for automatic scope addition
166
 */
167
public class AutoAddScopeProcessor {
168
    /**
169
     * Process auto-scope rules and transform matching classes
170
     */
171
    @BuildStep
172
    public AnnotationsTransformerBuildItem autoAddScopes(
173
        List<AutoAddScopeBuildItem> autoAddScopes,
174
        BeanArchiveIndexBuildItem beanArchiveIndex
175
    );
176
    
177
    /**
178
     * Validate auto-scope configuration
179
     */
180
    @BuildStep
181
    public void validateAutoScope(
182
        List<AutoAddScopeBuildItem> autoAddScopes,
183
        BuildProducer<ValidationPhaseBuildItem.ValidationErrorBuildItem> errors
184
    );
185
}
186
```
187

188
### Observer Validation Processor
189

190
Validates CDI observer methods and event handling configuration.
191

192
```java { .api }
193
/**
194
 * Processor for observer method validation
195
 */
196
public class ObserverValidationProcessor {
197
    /**
198
     * Validate observer method signatures and configuration
199
     */
200
    @BuildStep
201
    public void validateObservers(
202
        BeanArchiveIndexBuildItem beanArchiveIndex,
203
        List<ObserverTransformerBuildItem> observerTransformers,
204
        BuildProducer<ValidationPhaseBuildItem.ValidationErrorBuildItem> errors
205
    );
206
    
207
    /**
208
     * Process observer method transformations
209
     */
210
    @BuildStep
211
    public TransformedAnnotationsBuildItem transformObservers(
212
        List<ObserverTransformerBuildItem> observerTransformers,
213
        BeanArchiveIndexBuildItem beanArchiveIndex
214
    );
215
}
216
```
217

218
### Split Package Processor
219

220
Detects and handles split package scenarios in CDI applications.
221

222
```java { .api }
223
/**
224
 * Processor for split package detection and handling
225
 */
226
public class SplitPackageProcessor {
227
    /**
228
     * Detect split packages across bean archives
229
     */
230
    @BuildStep
231
    public void detectSplitPackages(
232
        BeanArchiveIndexBuildItem beanArchiveIndex,
233
        ArcConfig config,
234
        BuildProducer<ValidationPhaseBuildItem.ValidationErrorBuildItem> errors
235
    );
236
    
237
    /**
238
     * Configure split package handling
239
     */
240
    @BuildStep
241
    public SplitPackageConfigBuildItem configureSplitPackages(
242
        ArcConfig config
243
    );
244
}
245
```
246

247
### Configuration Processors
248

249
Handle build-time configuration processing and validation.
250

251
```java { .api }
252
/**
253
 * Configuration processing build step
254
 */
255
public class ConfigBuildStep {
256
    /**
257
     * Process ArC configuration and validate settings
258
     */
259
    @BuildStep
260
    public ArcConfigBuildItem processConfig(
261
        ArcConfig config,
262
        BuildProducer<ValidationPhaseBuildItem.ValidationErrorBuildItem> errors
263
    );
264
}
265

266
/**
267
 * Command line arguments processor for build-time configuration
268
 */
269
public class CommandLineArgumentsProcessor {
270
    /**
271
     * Process command line arguments affecting CDI configuration
272
     */
273
    @BuildStep
274
    public void processCommandLineArgs(
275
        List<CommandLineArgumentBuildItem> args,
276
        BuildProducer<ConfigPropertyBuildItem> configProperties
277
    );
278
}
279
```
280

281
### Lookup Conditions Processor
282

283
Handles conditional bean lookup and activation based on runtime conditions.
284

285
```java { .api }
286
/**
287
 * Processor for lookup conditions and conditional beans
288
 */
289
public class LookupConditionsProcessor {
290
    /**
291
     * Process lookup conditions for conditional bean activation
292
     */
293
    @BuildStep
294
    public void processLookupConditions(
295
        List<BuildTimeConditionBuildItem> buildTimeConditions,
296
        BeanArchiveIndexBuildItem beanArchiveIndex,
297
        BuildProducer<ConditionalBeanBuildItem> conditionalBeans
298
    );
299
}
300
```
301

302
### Bytecode Generation
303

304
Handles bytecode generation for optimized CDI components.
305

306
```java { .api }
307
/**
308
 * Adaptor for Gizmo bytecode generation during bean creation
309
 */
310
public class GeneratedBeanGizmoAdaptor implements ClassOutput {
311
    public GeneratedBeanGizmoAdaptor(BuildProducer<GeneratedBeanBuildItem> generatedBeans,
312
                                    boolean applicationClass);
313
    
314
    /**
315
     * Write generated class bytecode
316
     */
317
    @Override
318
    public void write(String name, byte[] data);
319
    
320
    /**
321
     * Get the generated class source information
322
     */
323
    public String getSource();
324
    
325
    /**
326
     * Check if this generates application classes
327
     */
328
    public boolean isApplicationClass();
329
}
330
```
331

332
**Usage Examples:**
333

334
```java
335
// Custom bytecode generation
336
@BuildStep
337
void generateCustomBeans(BuildProducer<GeneratedBeanBuildItem> generatedBeans) {
338
    GeneratedBeanGizmoAdaptor adaptor = new GeneratedBeanGizmoAdaptor(
339
        generatedBeans, true);
340
    
341
    try (ClassCreator creator = ClassCreator.builder()
342
            .classOutput(adaptor)
343
            .className("com.example.GeneratedService")
344
            .build()) {
345
        
346
        // Generate bean class
347
        creator.addAnnotation(ApplicationScoped.class);
348
        
349
        // Add methods
350
        MethodCreator method = creator.getMethodCreator("process", void.class);
351
        method.returnValue(null);
352
    }
353
}
354
```
355

356
### Development UI Processors
357

358
Processors for development mode UI and debugging capabilities.
359

360
```java { .api }
361
/**
362
 * Development UI processor for ArC information
363
 */
364
public class ArcDevUIProcessor {
365
    /**
366
     * Generate development UI data for CDI beans
367
     */
368
    @BuildStep
369
    public ArcBeanInfoBuildItem generateDevUIData(
370
        BeanContainerBuildItem beanContainer,
371
        BeanArchiveIndexBuildItem beanArchiveIndex
372
    );
373
}
374
```
375

376
### Lifecycle Processors
377

378
Handle application lifecycle events and build phase coordination.
379

380
```java { .api }
381
/**
382
 * Startup build steps processor
383
 */
384
public class StartupBuildSteps {
385
    /**
386
     * Configure startup event handling
387
     */
388
    @BuildStep
389
    @Record(ExecutionTime.STATIC_INIT)
390
    public void configureStartup(StartupRecorder recorder);
391
}
392

393
/**
394
 * Shutdown build steps processor
395
 */
396
public class ShutdownBuildSteps {
397
    /**
398
     * Configure shutdown event handling
399
     */
400
    @BuildStep  
401
    @Record(ExecutionTime.STATIC_INIT)
402
    public void configureShutdown(ShutdownRecorder recorder);
403
}
404
```
405

406
## Processor Patterns
407

408
### Build Step Dependencies
409

410
```java
411
@BuildStep
412
public OutputBuildItem processData(
413
    // Consumed build items (dependencies)
414
    InputBuildItem input,
415
    List<MultiBuildItem> multiples,
416
    
417
    // Produced build items (outputs)
418
    BuildProducer<ProducedBuildItem> producer
419
) {
420
    // Process inputs
421
    // Produce outputs via producer
422
    // Return single build item
423
}
424
```
425

426
### Recorder Integration
427

428
```java
429
@BuildStep
430
@Record(ExecutionTime.RUNTIME_INIT)
431
public void configureRuntime(
432
    BeanContainerBuildItem beanContainer,
433
    MyRecorder recorder
434
) {
435
    // Use recorder to capture runtime initialization logic
436
    recorder.initialize(beanContainer.getValue());
437
}
438
```
439

440
### Conditional Processing
441

442
```java
443
@BuildStep(onlyIf = DatabaseEnabled.class)
444
public DatabaseBuildItem setupDatabase() {
445
    return new DatabaseBuildItem();
446
}
447

448
public static class DatabaseEnabled implements BooleanSupplier {
449
    @Override
450
    public boolean getAsBoolean() {
451
        return ConfigProvider.getConfig()
452
            .getOptionalValue("database.enabled", Boolean.class)
453
            .orElse(false);
454
    }
455
}
456
```
457

458
Processors form the backbone of Quarkus's build-time CDI processing, enabling the creation of optimized, GraalVM-native compatible applications with fast startup times.