0
# Build Items
1

2
Build items are the primary API for extending Quarkus ArC's CDI functionality at build time. They provide type-safe communication between build steps and enable customization of bean discovery, registration, and container configuration.
3

4
## Capabilities
5

6
### Bean Registration
7

8
Register additional beans for CDI discovery and prevent beans from being removed during optimization.
9

10
```java { .api }
11
/**
12
 * Register additional bean classes for CDI discovery
13
 */
14
public class AdditionalBeanBuildItem extends MultiBuildItem {
15
    public AdditionalBeanBuildItem(String... beanClasses);
16
    public AdditionalBeanBuildItem(Class<?>... beanClasses);
17
    
18
    public static Builder builder();
19
    public static AdditionalBeanBuildItem unremovableOf(Class<?> beanClass);
20
    public static AdditionalBeanBuildItem unremovableOf(String beanClass);
21
    
22
    public List<String> getBeanClasses();
23
    public boolean contains(String beanClass);
24
    public boolean isRemovable();
25
    public DotName getDefaultScope();
26
}
27

28
/**
29
 * Builder for fluent AdditionalBeanBuildItem creation
30
 */
31
public static class AdditionalBeanBuildItem.Builder {
32
    public Builder addBeanClasses(String... beanClasses);
33
    public Builder addBeanClasses(Class<?>... beanClasses);
34
    public Builder setUnremovable();
35
    public Builder setRemovable();
36
    public Builder setDefaultScope(DotName scope);
37
    public Builder requiresContainerServices();
38
    public AdditionalBeanBuildItem build();
39
}
40
```
41

42
**Usage Examples:**
43

44
```java
45
// Register service classes as CDI beans
46
@BuildStep
47
AdditionalBeanBuildItem registerServices() {
48
    return AdditionalBeanBuildItem.builder()
49
        .addBeanClasses(MyService.class, MyRepository.class)
50
        .setUnremovable()
51
        .setDefaultScope(DotNames.APPLICATION_SCOPED)
52
        .build();
53
}
54

55
// Register beans by class name
56
@BuildStep
57
AdditionalBeanBuildItem registerByName() {
58
    return new AdditionalBeanBuildItem("com.example.Service", "com.example.Config");
59
}
60
```
61

62
### Synthetic Bean Creation
63

64
Create beans programmatically without requiring source classes, enabling advanced runtime configuration.
65

66
```java { .api }
67
/**
68
 * Register synthetic (programmatically created) beans
69
 */
70
public class SyntheticBeanBuildItem extends MultiBuildItem {
71
    public static ExtendedBeanConfigurator configure(Class<?> implClazz);
72
    public static ExtendedBeanConfigurator configure(DotName implClazz);
73
    public static ExtendedBeanConfigurator create(Class<?> implClazz);
74
    public static ExtendedBeanConfigurator create(DotName implClazz);
75
}
76

77
/**
78
 * Extended configurator for synthetic beans with Quarkus-specific features
79
 */
80
public static class SyntheticBeanBuildItem.ExtendedBeanConfigurator 
81
    extends BeanConfiguratorBase<SyntheticBeanBuildItem.ExtendedBeanConfigurator> {
82
    
83
    public SyntheticBeanBuildItem done();
84
    public ExtendedBeanConfigurator supplier(Supplier<?> supplier);
85
    public ExtendedBeanConfigurator runtimeValue(RuntimeValue<?> runtimeValue);
86
    public <T> ExtendedBeanConfigurator createWith(
87
        Function<SyntheticCreationalContext<T>, T> function);
88
    public ExtendedBeanConfigurator runtimeProxy(Object proxy);
89
    public ExtendedBeanConfigurator setRuntimeInit();
90
    public ExtendedBeanConfigurator checkActive(Supplier<ActiveResult> checkActive);
91
}
92
```
93

94
**Usage Examples:**
95

96
```java
97
// Create synthetic bean from supplier
98
@BuildStep
99
SyntheticBeanBuildItem createDatabaseConnection(DatabaseConfig config) {
100
    return SyntheticBeanBuildItem.configure(DatabaseConnection.class)
101
        .scope(ApplicationScoped.class)
102
        .supplier(() -> new DatabaseConnection(config.url(), config.username()))
103
        .done();
104
}
105

106
// Create synthetic bean with runtime initialization
107
@BuildStep
108
SyntheticBeanBuildItem createRuntimeService() {
109
    return SyntheticBeanBuildItem.configure(RuntimeService.class)
110
        .setRuntimeInit()
111
        .createWith(context -> {
112
            // Access to SyntheticCreationalContext for dependency injection
113
            return new RuntimeService(context.getBean(Configuration.class));
114
        })
115
        .done();
116
}
117
```
118

119
### Bean Exclusion and Protection
120

121
Control which beans are discovered and prevent important beans from being removed during optimization.
122

123
```java { .api }
124
/**
125
 * Mark beans as unremovable during unused bean removal
126
 */
127
public class UnremovableBeanBuildItem extends MultiBuildItem {
128
    public UnremovableBeanBuildItem(Predicate<BeanInfo> predicate);
129
    
130
    public static UnremovableBeanBuildItem beanClassNames(String... classNames);
131
    public static UnremovableBeanBuildItem beanClassNames(Set<String> classNames);
132
    public static UnremovableBeanBuildItem beanTypes(DotName... typeNames);
133
    public static UnremovableBeanBuildItem beanTypes(Class<?>... types);
134
    public static UnremovableBeanBuildItem beanTypes(Set<DotName> typeNames);
135
    public static UnremovableBeanBuildItem beanClassAnnotation(DotName annotationName);
136
    public static UnremovableBeanBuildItem targetWithAnnotation(DotName annotationName);
137
    
138
    public Predicate<BeanInfo> getPredicate();
139
    public Set<String> getClassNames();
140
}
141

142
/**
143
 * Exclude types from CDI discovery
144
 */
145
public class ExcludedTypeBuildItem extends MultiBuildItem {
146
    public ExcludedTypeBuildItem(String match);
147
    public String getMatch();
148
}
149
```
150

151
**Usage Examples:**
152

153
```java
154
// Protect specific bean classes from removal
155
@BuildStep
156
UnremovableBeanBuildItem protectServices() {
157
    return UnremovableBeanBuildItem.beanClassNames(
158
        "com.example.CriticalService",
159
        "com.example.SystemService"
160
    );
161
}
162

163
// Protect beans with specific annotations
164
@BuildStep
165
UnremovableBeanBuildItem protectAnnotatedBeans() {
166
    return UnremovableBeanBuildItem.beanClassAnnotation(
167
        DotName.createSimple("com.example.Important")
168
    );
169
}
170

171
// Exclude packages from discovery  
172
@BuildStep
173
ExcludedTypeBuildItem excludeTestPackages() {
174
    return new ExcludedTypeBuildItem("com.example.test.**");
175
}
176
```
177

178
### Bean Metadata and Discovery
179

180
Provide information about bean archives and control bean discovery phases.
181

182
```java { .api }
183
/**
184
 * Jandex index with complete CDI information
185
 */
186
public class BeanArchiveIndexBuildItem extends SimpleBuildItem {
187
    public BeanArchiveIndexBuildItem(IndexView index, IndexView immutableIndex, 
188
                                    Set<DotName> generatedClassNames);
189
    
190
    public IndexView getIndex();
191
    public IndexView getImmutableIndex();
192
    public Set<DotName> getGeneratedClassNames();
193
}
194

195
/**
196
 * Marks completion of bean discovery phase
197
 */
198
public class BeanDiscoveryFinishedBuildItem extends SimpleBuildItem {
199
    // Marker build item indicating bean discovery is complete
200
}
201

202
/**
203
 * Bean registration phase marker
204
 */
205
public class BeanRegistrationPhaseBuildItem extends SimpleBuildItem {
206
    public BeanRegistrationPhaseBuildItem(BeanProcessor.Builder builder);
207
    public BeanProcessor.Builder getBeanProcessor();
208
}
209
```
210

211
### Custom Scopes and Annotations
212

213
Register custom CDI scopes and bean-defining annotations.
214

215
```java { .api }
216
/**
217
 * Register custom CDI scope annotations
218
 */
219
public class CustomScopeBuildItem extends MultiBuildItem {
220
    public CustomScopeBuildItem(Class<? extends Annotation> scope);
221
    public CustomScopeBuildItem(DotName annotationName);
222
    public DotName getAnnotationName();
223
}
224

225
/**
226
 * Register additional bean-defining annotations
227
 */
228
public class BeanDefiningAnnotationBuildItem extends MultiBuildItem {
229
    public BeanDefiningAnnotationBuildItem(DotName name);
230
    public BeanDefiningAnnotationBuildItem(DotName name, DotName defaultScope);
231
    public BeanDefiningAnnotationBuildItem(DotName name, DotName defaultScope, boolean removable);
232
    
233
    public DotName getName();
234
    public DotName getDefaultScope();
235
    public boolean isRemovable();
236
}
237

238
/**
239
 * Automatically add scope annotations to classes
240
 */
241
public class AutoAddScopeBuildItem extends MultiBuildItem {
242
    public static Builder builder();
243
    
244
    public boolean isContainerServicesRequired();
245
    public DotName getDefaultScope();
246
    public boolean isUnremovable();
247
    public String getReason();
248
    public int getPriority();
249
    public boolean test(ClassInfo clazz, Collection<AnnotationInstance> annotations, IndexView index);
250
}
251
```
252

253
**Usage Examples:**
254

255
```java
256
// Register custom scope
257
@BuildStep
258
CustomScopeBuildItem registerCustomScope() {
259
    return new CustomScopeBuildItem(TenantScoped.class);
260
}
261

262
// Auto-add scopes to matching classes
263
@BuildStep
264
AutoAddScopeBuildItem autoScopeServices() {
265
    return AutoAddScopeBuildItem.builder()
266
        .containsOne("com.example.service")
267
        .defaultScope(DotNames.APPLICATION_SCOPED)
268
        .reason("Service classes should be application scoped")
269
        .build();
270
}
271
```
272

273
### Generated Classes
274

275
Handle dynamically generated bean classes during the build process.
276

277
```java { .api }
278
/**
279
 * Represents a generated CDI bean class
280
 */
281
public class GeneratedBeanBuildItem extends MultiBuildItem {
282
    public GeneratedBeanBuildItem(String name, byte[] data);
283
    public GeneratedBeanBuildItem(String name, byte[] data, String source);
284
    public GeneratedBeanBuildItem(String name, byte[] data, String source, boolean applicationClass);
285
    
286
    public String getName();
287
    public byte[] getData();
288
    public String getSource();
289
    public boolean isApplicationClass();
290
}
291
```
292

293
### Annotation and Metadata Transformation
294

295
Transform annotations and metadata on CDI components during the build process.
296

297
```java { .api }
298
/**
299
 * Transform annotations on CDI components
300
 */
301
public class AnnotationsTransformerBuildItem extends MultiBuildItem {
302
    public AnnotationsTransformerBuildItem(AnnotationsTransformer transformer);
303
    public AnnotationsTransformer getAnnotationsTransformer();
304
}
305

306
/**
307
 * Transform injection point qualifiers
308
 */
309
public class InjectionPointTransformerBuildItem extends MultiBuildItem {
310
    public InjectionPointTransformerBuildItem(InjectionPointsTransformer transformer);
311
    public InjectionPointsTransformer getTransformer();
312
}
313

314
/**
315
 * Transform observer methods
316
 */
317
public class ObserverTransformerBuildItem extends MultiBuildItem {
318
    public ObserverTransformerBuildItem(ObserverTransformer transformer);
319
    public ObserverTransformer getObserverTransformer();
320
}
321

322
/**
323
 * Define auto-inject annotations for fields
324
 */
325
public class AutoInjectAnnotationBuildItem extends MultiBuildItem {
326
    public AutoInjectAnnotationBuildItem(DotName annotationName);
327
    public DotName getAnnotationName();
328
}
329
```
330

331
### Interceptor and AOP Support
332

333
Register interceptor binding annotations and support method interception.
334

335
```java { .api }
336
/**
337
 * Register interceptor binding annotations
338
 */
339
public class InterceptorBindingRegistrarBuildItem extends MultiBuildItem {
340
    public InterceptorBindingRegistrarBuildItem(InterceptorBindingRegistrar registrar);
341
    public InterceptorBindingRegistrar getInterceptorBindingRegistrar();
342
}
343

344
/**
345
 * Access to the interceptor resolver
346
 */
347
public class InterceptorResolverBuildItem extends SimpleBuildItem {
348
    public InterceptorResolverBuildItem(InterceptorResolver interceptorResolver);
349
    public InterceptorResolver getInterceptorResolver();
350
}
351

352
/**
353
 * Support for static method interception
354
 */
355
public class InterceptedStaticMethodBuildItem extends MultiBuildItem {
356
    public InterceptedStaticMethodBuildItem(String className, String methodName, 
357
                                           Type returnType, Type[] parameterTypes);
358
    public String getClassName();
359
    public String getMethodName();
360
    public Type getReturnType();
361
    public Type[] getParameterTypes();
362
}
363
```
364

365
### Context and Scope Management
366

367
Manage CDI contexts and custom scope implementations.
368

369
```java { .api }
370
/**
371
 * Context registration phase access
372
 */
373
public class ContextRegistrationPhaseBuildItem extends SimpleBuildItem {
374
    public static class ContextConfiguratorBuildItem extends MultiBuildItem {
375
        // Nested class for context configurators
376
    }
377
}
378

379
/**
380
 * Custom current context factory provider
381
 */
382
public class CurrentContextFactoryBuildItem extends SimpleBuildItem {
383
    public CurrentContextFactoryBuildItem(RuntimeValue<CurrentContextFactory> factory);
384
    public RuntimeValue<CurrentContextFactory> getFactory();
385
}
386

387
/**
388
 * Information about custom scopes
389
 */
390
public class CustomScopeAnnotationsBuildItem extends SimpleBuildItem {
391
    public CustomScopeAnnotationsBuildItem(Set<DotName> customScopeNames);
392
    public Set<DotName> getCustomScopeNames();
393
    public boolean isScopeIn(Collection<AnnotationInstance> annotations);
394
}
395
```
396

397
### Qualifier and Stereotype Registration
398

399
Register CDI qualifiers and stereotype annotations.
400

401
```java { .api }
402
/**
403
 * Register qualifier annotations
404
 */
405
public class QualifierRegistrarBuildItem extends MultiBuildItem {
406
    public QualifierRegistrarBuildItem(QualifierRegistrar registrar);
407
    public QualifierRegistrar getQualifierRegistrar();
408
}
409

410
/**
411
 * Register stereotype annotations
412
 */
413
public class StereotypeRegistrarBuildItem extends MultiBuildItem {
414
    public StereotypeRegistrarBuildItem(StereotypeRegistrar registrar);
415
    public StereotypeRegistrar getStereotypeRegistrar();
416
}
417

418
/**
419
 * Build-time enabled stereotypes information
420
 */
421
public class BuildTimeEnabledStereotypesBuildItem extends SimpleBuildItem {
422
    public BuildTimeEnabledStereotypesBuildItem(Set<DotName> stereotypes);
423
    public Set<DotName> getStereotypes();
424
}
425
```
426

427
### Configuration and Conditions
428

429
Handle build-time configuration and conditional logic.
430

431
```java { .api }
432
/**
433
 * Validate mandatory config properties at runtime
434
 */
435
public class ConfigPropertyBuildItem extends MultiBuildItem {
436
    public ConfigPropertyBuildItem(String propertyName, Type propertyType, 
437
                                  String defaultValue, ExecutionTime executionTime);
438
    public String getPropertyName();
439
    public Type getPropertyType();
440
    public String getDefaultValue();
441
    public ExecutionTime getExecutionTime();
442
}
443

444
/**
445
 * Handle build-time conditions
446
 */
447
public class BuildTimeConditionBuildItem extends MultiBuildItem {
448
    public BuildTimeConditionBuildItem(Predicate<BuildTimeConditionEvaluator.BuildTimeConditionContext> condition, 
449
                                      boolean enabledWhenMatched);
450
    public Predicate<BuildTimeConditionEvaluator.BuildTimeConditionContext> getCondition();
451
    public boolean isEnabledWhenMatched();
452
}
453

454
/**
455
 * Excluded build-time condition information
456
 */
457
public class BuildExclusionsBuildItem extends SimpleBuildItem {
458
    public BuildExclusionsBuildItem(Set<String> excludedTypes, 
459
                                   Function<String, Optional<Predicate<BeanInfo>>> predicateFunction);
460
    public Set<String> getExcludedTypes();
461
    public Function<String, Optional<Predicate<BeanInfo>>> getPredicateFunction();
462
}
463
```
464

465
### Archive and Discovery Control
466

467
Control bean archive discovery and package handling.
468

469
```java { .api }
470
/**
471
 * Register logic to identify bean archives
472
 */
473
public class BeanArchivePredicateBuildItem extends MultiBuildItem {
474
    public BeanArchivePredicateBuildItem(Predicate<ApplicationArchive> predicate);
475
    public Predicate<ApplicationArchive> getPredicate();
476
}
477

478
/**
479
 * Mark bean archives as Quarkus-compatible
480
 */
481
public class KnownCompatibleBeanArchiveBuildItem extends MultiBuildItem {
482
    public KnownCompatibleBeanArchiveBuildItem(String groupId, String artifactId);
483
    public String getGroupId();
484
    public String getArtifactId();
485
}
486

487
/**
488
 * Exclude packages from split package detection
489
 */
490
public class IgnoreSplitPackageBuildItem extends MultiBuildItem {
491
    public IgnoreSplitPackageBuildItem(String packageName);
492
    public String getPackageName();
493
}
494

495
/**
496
 * Final application class predicate
497
 */
498
public class CompletedApplicationClassPredicateBuildItem extends SimpleBuildItem {
499
    public CompletedApplicationClassPredicateBuildItem(Predicate<DotName> predicate);
500
    public Predicate<DotName> getPredicate();
501
}
502
```
503

504
### Reflection and Code Generation
505

506
Handle reflection requirements and code generation phases.
507

508
```java { .api }
509
/**
510
 * Request reflective access for bean classes
511
 */
512
public class ReflectiveBeanClassBuildItem extends MultiBuildItem {
513
    public ReflectiveBeanClassBuildItem(String className);
514
    public String getClassName();
515
}
516

517
/**
518
 * Resource generation phase marker
519
 */
520
public class ResourcesGeneratedPhaseBuildItem extends EmptyBuildItem {
521
    // Phase marker for resource generation completion
522
}
523

524
/**
525
 * Method invoker creation access
526
 */
527
public class InvokerFactoryBuildItem extends MultiBuildItem {
528
    public InvokerFactoryBuildItem(InvokerFactory invokerFactory);
529
    public InvokerFactory getInvokerFactory();
530
}
531
```
532

533
### Integration and Extensions
534

535
Handle CDI extensions and integration with other systems.
536

537
```java { .api }
538
/**
539
 * CDI Lite build compatible extensions entry point
540
 */
541
public class BuildCompatibleExtensionsBuildItem extends SimpleBuildItem {
542
    public BuildCompatibleExtensionsBuildItem(BuildCompatibleExtensions extensions);
543
    public BuildCompatibleExtensions getExtensions();
544
}
545

546
/**
547
 * Non-CDI resource injection support
548
 */
549
public class ResourceAnnotationBuildItem extends MultiBuildItem {
550
    public ResourceAnnotationBuildItem(DotName name);
551
    public DotName getName();
552
}
553

554
/**
555
 * OpenTelemetry integration configuration
556
 */
557
public class OpenTelemetrySdkBuildItem extends SimpleBuildItem {
558
    // OpenTelemetry SDK configuration information
559
}
560

561
/**
562
 * Runtime-init synthetic bean coordination
563
 */
564
public class SyntheticBeansRuntimeInitBuildItem extends EmptyBuildItem {
565
    // Marker for runtime-init synthetic beans
566
}
567
```
568

569
### Validation and Build Phases
570

571
Control validation phases and build completion markers.
572

573
```java { .api }
574
/**
575
 * Validation phase marker with error reporting
576
 */
577
public class ValidationPhaseBuildItem extends SimpleBuildItem {
578
    public ValidationPhaseBuildItem(
579
        BeanDeploymentValidator.ValidationContext validationContext,
580
        BeanProcessor beanProcessor
581
    );
582
    
583
    public static class ValidationErrorBuildItem extends MultiBuildItem {
584
        public ValidationErrorBuildItem(Throwable error);
585
        public Throwable getError();
586
    }
587
}
588

589
/**
590
 * Observer registration phase access
591
 */
592
public class ObserverRegistrationPhaseBuildItem extends SimpleBuildItem {
593
    public static class ObserverConfiguratorBuildItem extends MultiBuildItem {
594
        // Nested class for observer configurators
595
    }
596
}
597

598
/**
599
 * Component inspection access
600
 */
601
public class SynthesisFinishedBuildItem extends SimpleBuildItem {
602
    public SynthesisFinishedBuildItem(List<BeanInfo> beans, List<ObserverInfo> observers);
603
    public List<BeanInfo> getBeans();
604
    public List<ObserverInfo> getObservers();
605
}
606

607
/**
608
 * Pre-container initialization marker
609
 */
610
public class PreBeanContainerBuildItem extends SimpleBuildItem {
611
    // Marker for pre-container build phase
612
}
613

614
/**
615
 * Registered components inspection
616
 */
617
public class RegisteredComponentsBuildItem extends SimpleBuildItem {
618
    // Base class for component inspection during build
619
}
620

621
/**
622
 * Query transformed annotations
623
 */
624
public class TransformedAnnotationsBuildItem extends SimpleBuildItem {
625
    public TransformedAnnotationsBuildItem(AnnotationStore annotationStore);
626
    public AnnotationStore getAnnotations();
627
}
628
```
629

630
## Build Item Categories
631

632
### MultiBuildItem vs SimpleBuildItem
633

634
- **MultiBuildItem**: Multiple instances allowed per build (e.g., AdditionalBeanBuildItem)
635
- **SimpleBuildItem**: Single instance per build (e.g., BeanContainerBuildItem)
636
- **EmptyBuildItem**: Marker items with no data, used for phase coordination
637

638
### Build Item Usage Patterns
639

640
1. **Registration**: Add new beans, scopes, or annotations
641
2. **Protection**: Prevent bean removal or mark as unremovable  
642
3. **Configuration**: Customize CDI behavior and settings
643
4. **Transformation**: Modify existing beans or annotations
644
5. **Phase Control**: Coordinate build phases and dependencies