0
# Quarkus ArC Deployment
1

2
Quarkus ArC Deployment is the build-time component of Quarkus's optimized CDI (Contexts and Dependency Injection) implementation. It processes CDI beans, interceptors, decorators, and observers at build time to generate optimized bytecode, eliminating runtime reflection and enabling fast startup times with reduced memory footprint.
3

4
## Package Information
5

6
- **Package Name**: quarkus-arc-deployment
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: io.quarkus
10
- **Artifact ID**: quarkus-arc-deployment  
11
- **Installation**: Add to Maven pom.xml:
12

13
```xml
14
<dependency>
15
    <groupId>io.quarkus</groupId>
16
    <artifactId>quarkus-arc-deployment</artifactId>
17
    <version>3.23.0</version>
18
    <scope>provided</scope>
19
</dependency>
20
```
21

22
## Core Imports
23

24
```java
25
// Core build items for extending CDI functionality
26
import io.quarkus.arc.deployment.AdditionalBeanBuildItem;
27
import io.quarkus.arc.deployment.SyntheticBeanBuildItem;
28
import io.quarkus.arc.deployment.UnremovableBeanBuildItem;
29
import io.quarkus.arc.deployment.BeanContainerBuildItem;
30
import io.quarkus.arc.deployment.BeanArchiveIndexBuildItem;
31
import io.quarkus.arc.deployment.BeanRegistrationPhaseBuildItem;
32
import io.quarkus.arc.deployment.ValidationPhaseBuildItem;
33

34
// Configuration interfaces
35
import io.quarkus.arc.deployment.ArcConfig;
36
import io.quarkus.arc.deployment.ArcConfig.OptimizeContexts;
37

38
// Annotation and metadata transformation
39
import io.quarkus.arc.deployment.AnnotationsTransformerBuildItem;
40
import io.quarkus.arc.deployment.InjectionPointTransformerBuildItem;
41
import io.quarkus.arc.deployment.ObserverTransformerBuildItem;
42

43
// Scope and context management
44
import io.quarkus.arc.deployment.CustomScopeBuildItem;
45
import io.quarkus.arc.deployment.ContextRegistrationPhaseBuildItem;
46
import io.quarkus.arc.deployment.CurrentContextFactoryBuildItem;
47

48
// Interceptor and AOP support
49
import io.quarkus.arc.deployment.InterceptorBindingRegistrarBuildItem;
50
import io.quarkus.arc.deployment.InterceptorResolverBuildItem;
51
import io.quarkus.arc.deployment.InterceptedStaticMethodBuildItem;
52

53
// Build processors and steps
54
import io.quarkus.arc.deployment.ArcProcessor;
55
import io.quarkus.deployment.annotations.BuildStep;
56
import io.quarkus.deployment.annotations.Record;
57
import io.quarkus.deployment.annotations.ExecutionTime;
58

59
// Jandex indexing
60
import org.jboss.jandex.DotName;
61
import org.jboss.jandex.IndexView;
62
import org.jboss.jandex.AnnotationInstance;
63
```
64

65
## Basic Usage
66

67
```java
68
// Example Quarkus extension using ArC deployment APIs
69
@BuildStep
70
AdditionalBeanBuildItem registerBeans() {
71
    return AdditionalBeanBuildItem.builder()
72
        .addBeanClasses(MyService.class, MyConfiguration.class)
73
        .setUnremovable()
74
        .build();
75
}
76

77
@BuildStep
78
SyntheticBeanBuildItem createSyntheticBean() {
79
    return SyntheticBeanBuildItem.configure(MyRuntimeBean.class)
80
        .scope(ApplicationScoped.class)
81
        .supplier(() -> new MyRuntimeBean())
82
        .done();
83
}
84
```
85

86
## Architecture
87

88
Quarkus ArC Deployment is built around several key architectural patterns:
89

90
- **Build Items**: Primary extension API providing type-safe communication between build steps
91
- **Build Processors**: Classes containing @BuildStep methods that consume and produce build items
92
- **Configuration**: Typed configuration interfaces for build-time CDI settings
93
- **Synthetic Components**: Programmatic creation of CDI beans, interceptors, and observers
94
- **Bean Discovery**: Automated scanning and registration of CDI components
95
- **Optimization**: Build-time analysis for unused bean removal and context optimization
96

97
## Capabilities
98

99
### Build Items API
100

101
Core build items for registering beans, configuring CDI behavior, and extending the container at build time. These are the primary integration points for Quarkus extensions.
102

103
```java { .api }
104
// Register additional bean classes for CDI discovery
105
public class AdditionalBeanBuildItem extends MultiBuildItem {
106
    public AdditionalBeanBuildItem(String... beanClasses);
107
    public AdditionalBeanBuildItem(Class<?>... beanClasses);
108
    public static Builder builder();
109
}
110

111
// Create synthetic beans programmatically
112
public class SyntheticBeanBuildItem extends MultiBuildItem {
113
    public static ExtendedBeanConfigurator configure(Class<?> implClazz);
114
    public static ExtendedBeanConfigurator configure(DotName implClazz);
115
}
116

117
// Mark beans as unremovable during unused bean removal
118
public class UnremovableBeanBuildItem extends MultiBuildItem {
119
    public static UnremovableBeanBuildItem beanClassNames(String... classNames);
120
    public static UnremovableBeanBuildItem beanTypes(Class<?>... types);
121
    public static UnremovableBeanBuildItem beanClassAnnotation(DotName annotationName);
122
}
123
```
124

125
[Build Items](./build-items.md)
126

127
### Configuration API
128

129
Build-time configuration interfaces for customizing CDI container behavior, bean discovery, and optimization settings.
130

131
```java { .api }
132
// Main ArC configuration interface
133
public interface ArcConfig {
134
    String removeUnusedBeans();
135
    boolean autoInjectFields();
136
    boolean transformUnproxyableClasses();
137
    Optional<List<String>> selectedAlternatives();
138
    Optional<List<String>> excludeTypes();
139
    boolean detectWrongAnnotations();
140
    boolean strictCompatibility();
141
}
142
```
143

144
[Configuration](./configuration.md)
145

146
### Bean Container Integration
147

148
Integration with the CDI bean container, providing access to the fully initialized container and registration of container listeners.
149

150
```java { .api }
151
// Access to the fully initialized CDI bean container
152
public class BeanContainerBuildItem extends SimpleBuildItem {
153
    public BeanContainerBuildItem(BeanContainer value);
154
    public BeanContainer getValue();
155
}
156

157
// Register listeners for bean container initialization
158
public class BeanContainerListenerBuildItem extends MultiBuildItem {
159
    public BeanContainerListenerBuildItem(BeanContainerListener beanContainerListener);
160
    public BeanContainerListener getBeanContainerListener();
161
}
162
```
163

164
[Bean Container](./bean-container.md)
165

166
### Annotation and Metadata Transformation
167

168
Transform annotations and metadata on CDI components during the build process for customization and optimization.
169

170
```java { .api }
171
// Transform annotations on CDI components
172
public class AnnotationsTransformerBuildItem extends MultiBuildItem {
173
    public AnnotationsTransformerBuildItem(AnnotationsTransformer transformer);
174
    public AnnotationsTransformer getAnnotationsTransformer();
175
}
176

177
// Transform injection point qualifiers
178
public class InjectionPointTransformerBuildItem extends MultiBuildItem {
179
    public InjectionPointTransformerBuildItem(InjectionPointsTransformer transformer);
180
    public InjectionPointsTransformer getTransformer();
181
}
182
```
183

184
### Context and Scope Management
185

186
Manage CDI contexts and custom scope implementations with full lifecycle control.
187

188
```java { .api }
189
// Register custom CDI scope annotations
190
public class CustomScopeBuildItem extends MultiBuildItem {
191
    public CustomScopeBuildItem(Class<? extends Annotation> scope);
192
    public CustomScopeBuildItem(DotName annotationName);
193
}
194

195
// Context registration phase access
196
public class ContextRegistrationPhaseBuildItem extends SimpleBuildItem {
197
    // Provides access to context registration configurators
198
}
199
```
200

201
### Interceptor and AOP Support
202

203
Comprehensive support for interceptors, method interception, and aspect-oriented programming features.
204

205
```java { .api }
206
// Register interceptor binding annotations
207
public class InterceptorBindingRegistrarBuildItem extends MultiBuildItem {
208
    public InterceptorBindingRegistrarBuildItem(InterceptorBindingRegistrar registrar);
209
    public InterceptorBindingRegistrar getInterceptorBindingRegistrar();
210
}
211

212
// Support for static method interception
213
public class InterceptedStaticMethodBuildItem extends MultiBuildItem {
214
    public InterceptedStaticMethodBuildItem(String className, String methodName, 
215
                                           Type returnType, Type[] parameterTypes);
216
}
217
```
218

219
### Build Phases and Lifecycle
220

221
Control build phases, validation, and lifecycle events throughout the CDI container construction process.
222

223
```java { .api }
224
// Bean registration phase marker
225
public class BeanRegistrationPhaseBuildItem extends SimpleBuildItem {
226
    public BeanRegistrationPhaseBuildItem(BeanProcessor.Builder builder);
227
    public BeanProcessor.Builder getBeanProcessor();
228
}
229

230
// Validation phase with error reporting
231
public class ValidationPhaseBuildItem extends SimpleBuildItem {
232
    public static class ValidationErrorBuildItem extends MultiBuildItem {
233
        public ValidationErrorBuildItem(Throwable error);
234
    }
235
}
236
```
237

238
### Advanced CDI Features
239

240
Support for advanced CDI features including custom scopes, observers, qualifiers, and stereotypes with build-time transformation capabilities.
241

242
```java { .api }
243
// Register custom CDI scope annotations
244
public class CustomScopeBuildItem extends MultiBuildItem {
245
    public CustomScopeBuildItem(Class<? extends Annotation> scope);
246
    public CustomScopeBuildItem(DotName annotationName);
247
}
248

249
// Transform annotations on CDI components
250
public class AnnotationsTransformerBuildItem extends MultiBuildItem {
251
    public AnnotationsTransformerBuildItem(AnnotationTransformation transformation);
252
    public AnnotationTransformation getAnnotationTransformation();
253
}
254
```
255

256
[Advanced Features](./advanced-features.md)
257

258
### Archive and Discovery Control
259

260
Control bean archive discovery, indexing, and package handling with flexible configuration options.
261

262
```java { .api }
263
// Jandex index with complete CDI information
264
public class BeanArchiveIndexBuildItem extends SimpleBuildItem {
265
    public BeanArchiveIndexBuildItem(IndexView index, IndexView immutableIndex, 
266
                                    Set<DotName> generatedClassNames);
267
    public IndexView getIndex();
268
}
269

270
// Register logic to identify bean archives
271
public class BeanArchivePredicateBuildItem extends MultiBuildItem {
272
    public BeanArchivePredicateBuildItem(Predicate<ApplicationArchive> predicate);
273
}
274
```
275

276
### Configuration and Conditions
277

278
Handle build-time configuration, conditional logic, and environment-specific behavior.
279

280
```java { .api }
281
// Validate mandatory config properties at runtime
282
public class ConfigPropertyBuildItem extends MultiBuildItem {
283
    public ConfigPropertyBuildItem(String propertyName, Type propertyType, 
284
                                  String defaultValue, ExecutionTime executionTime);
285
}
286

287
// Handle build-time conditions
288
public class BuildTimeConditionBuildItem extends MultiBuildItem {
289
    public BuildTimeConditionBuildItem(Predicate<BuildTimeConditionEvaluator.BuildTimeConditionContext> condition, 
290
                                      boolean enabledWhenMatched);
291
}
292
```
293

294
### Reflection and Code Generation
295

296
Handle reflection requirements, code generation phases, and bytecode manipulation.
297

298
```java { .api }
299
// Request reflective access for bean classes
300
public class ReflectiveBeanClassBuildItem extends MultiBuildItem {
301
    public ReflectiveBeanClassBuildItem(String className);
302
}
303

304
// Represents a generated CDI bean class
305
public class GeneratedBeanBuildItem extends MultiBuildItem {
306
    public GeneratedBeanBuildItem(String name, byte[] data, String source, boolean applicationClass);
307
}
308
```
309

310
### Processors and Build Steps
311

312
Core processors implementing the CDI build-time logic and extension points for custom build step integration.
313

314
```java { .api }
315
// Main ArC processor with CDI build steps
316
public class ArcProcessor {
317
    @BuildStep
318
    public BeanContainerBuildItem build(/* various build items */);
319
    
320
    @BuildStep
321
    public ValidationPhaseBuildItem validate(/* validation inputs */);
322
    
323
    @BuildStep
324
    public BeanRegistrationPhaseBuildItem registerBeans(/* registration inputs */);
325
}
326

327
// Adaptor for bytecode generation during bean creation
328
public class GeneratedBeanGizmoAdaptor implements ClassOutput {
329
    public void write(String name, byte[] data);
330
    public String getSource();
331
    public boolean isApplicationClass();
332
}
333
```
334

335
[Processors](./processors.md)
336

337
## Types
338

339
### Core Build Item Types
340

341
```java { .api }
342
// Base classes for build items
343
public abstract class MultiBuildItem {
344
    // Multiple instances allowed per build
345
}
346

347
public abstract class SimpleBuildItem {
348
    // Single instance per build
349
}
350

351
// Builder pattern for additional beans
352
public static class AdditionalBeanBuildItem.Builder {
353
    public Builder addBeanClasses(String... beanClasses);
354
    public Builder addBeanClasses(Class<?>... beanClasses);
355
    public Builder setUnremovable();
356
    public Builder setDefaultScope(DotName scope);
357
    public AdditionalBeanBuildItem build();
358
}
359
```
360

361
### Synthetic Bean Configuration
362

363
```java { .api }
364
// Extended configurator for synthetic beans
365
public static class SyntheticBeanBuildItem.ExtendedBeanConfigurator 
366
    extends BeanConfiguratorBase<SyntheticBeanBuildItem.ExtendedBeanConfigurator> {
367
    
368
    public SyntheticBeanBuildItem done();
369
    public ExtendedBeanConfigurator supplier(Supplier<?> supplier);
370
    public ExtendedBeanConfigurator runtimeValue(RuntimeValue<?> runtimeValue);
371
    public ExtendedBeanConfigurator setRuntimeInit();
372
}
373
```
374

375
### Configuration Interfaces
376

377
```java { .api }
378
// Main configuration interface with all build-time settings
379
public interface ArcConfig {
380
    String removeUnusedBeans();
381
    boolean autoInjectFields();
382
    boolean transformUnproxyableClasses();
383
    boolean transformPrivateInjectedFields();
384
    boolean failOnInterceptedPrivateMethod();
385
    Optional<List<String>> selectedAlternatives();
386
    boolean autoProducerMethods();
387
    Optional<List<String>> excludeTypes();
388
    Optional<List<String>> unremovableTypes();
389
    Map<String, IndexDependencyConfig> excludeDependency();
390
    boolean detectUnusedFalsePositives();
391
    boolean detectWrongAnnotations();
392
    boolean strictCompatibility();
393
    ArcDevModeConfig devMode();
394
    ArcTestConfig test();
395
    Optional<List<String>> ignoredSplitPackages();
396
    ArcContextPropagationConfig contextPropagation();
397
    OptimizeContexts optimizeContexts();
398
}
399

400
// Development mode configuration
401
public interface ArcDevModeConfig {
402
    boolean monitoringEnabled();
403
    boolean lifecycleEvents();
404
}
405

406
// Test mode configuration  
407
public interface ArcTestConfig {
408
    boolean disableApplicationIndex();
409
    boolean transformTestClasses();
410
}
411

412
// Context propagation configuration
413
public interface ArcContextPropagationConfig {
414
    boolean enabled();
415
    Optional<List<String>> propagatedContexts();
416
}
417

418
// Index dependency configuration
419
public interface IndexDependencyConfig {
420
    Optional<String> groupId();
421
    Optional<String> artifactId();
422
    Optional<String> classifier();
423
}
424
```
425

426
### Configuration Enums
427

428
```java { .api }
429
// Context optimization strategies
430
public enum OptimizeContexts {
431
    AUTO,     // Automatically determine optimization based on usage
432
    ENABLED,  // Force enable context optimization
433
    DISABLED  // Disable context optimization
434
}
435
```
436

437
### Build Item Categories
438

439
```java { .api }
440
// Base build item types
441
public abstract class MultiBuildItem {
442
    // Multiple instances allowed per build step
443
}
444

445
public abstract class SimpleBuildItem {
446
    // Single instance per build step
447
}
448

449
public abstract class EmptyBuildItem {
450
    // Marker build items with no data payload
451
}
452
```
453

454
### Transformer and Registrar Interfaces
455

456
```java { .api }
457
// Annotation transformation interface
458
public interface AnnotationsTransformer {
459
    boolean appliesTo(AnnotationTarget.Kind kind);
460
    void transform(TransformationContext transformationContext);
461
}
462

463
// Injection point transformation interface
464
public interface InjectionPointsTransformer {
465
    boolean appliesTo(Type requiredType, Set<Annotation> qualifiers);
466
    void transform(TransformationContext transformationContext);
467
}
468

469
// Observer transformation interface  
470
public interface ObserverTransformer {
471
    boolean appliesTo(MethodInfo observerMethod, AnnotationInstance observesAnnotation);
472
    void transform(ObserverTransformationContext transformationContext);
473
}
474

475
// Interceptor binding registrar interface
476
public interface InterceptorBindingRegistrar {
477
    void register(RegistrationContext registrationContext);
478
}
479

480
// Qualifier registrar interface
481
public interface QualifierRegistrar {
482
    void register(RegistrationContext registrationContext);
483
}
484

485
// Stereotype registrar interface
486
public interface StereotypeRegistrar {
487
    void register(RegistrationContext registrationContext);
488
}
489
```
490

491
### Utility and Helper Types
492

493
```java { .api }
494
// Bean container interface for runtime access
495
public interface BeanContainer {
496
    <T> T select(Class<T> type, Annotation... qualifiers);
497
    boolean hasBean(Class<?> type, Annotation... qualifiers);
498
    void destroy(Object instance);
499
}
500

501
// Bean container listener for initialization callbacks
502
public interface BeanContainerListener {
503
    void created(BeanContainer container);
504
}
505

506
// Runtime value wrapper for recorder integration
507
public interface RuntimeValue<T> {
508
    T getValue();
509
}
510

511
// Synthetic creational context for programmatic bean creation
512
public interface SyntheticCreationalContext<T> {
513
    <U> U getBean(Class<U> type, Annotation... qualifiers);
514
    T create();
515
}
516
```