0
# Quarkus Arc
1

2
Quarkus Arc is a build-time CDI (Contexts and Dependency Injection) dependency injection framework that is part of the Quarkus ecosystem. This extension provides compile-time dependency injection capabilities optimized for cloud-native and containerized Java applications. Arc processes CDI annotations at build time rather than runtime, enabling faster startup times and reduced memory footprint typical of traditional CDI implementations.
3

4
## Package Information
5

6
- **Package Name**: quarkus-arc
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add dependency to `pom.xml`:
10

11
```xml
12
<dependency>
13
    <groupId>io.quarkus</groupId>
14
    <artifactId>quarkus-arc</artifactId>
15
    <version>3.23.0</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
import io.quarkus.arc.profile.IfBuildProfile;
23
import io.quarkus.arc.profile.UnlessBuildProfile;
24
import io.quarkus.arc.properties.IfBuildProperty;
25
import io.quarkus.arc.properties.UnlessBuildProperty;
26
import io.quarkus.arc.lookup.LookupIfProperty;
27
import io.quarkus.arc.lookup.LookupUnlessProperty;
28
import io.quarkus.arc.log.LoggerName;
29
import io.quarkus.arc.runtime.BeanContainer;
30
import io.quarkus.arc.runtime.BeanContainerListener;
31
import io.quarkus.arc.runtime.BeanInvoker;
32
import io.quarkus.arc.runtime.BeanLookupSupplier;
33
import io.quarkus.arc.runtime.InterceptorBindings;
34
```
35

36
For accessing the Arc container at runtime:
37

38
```java
39
import io.quarkus.arc.Arc;
40
import io.quarkus.arc.ArcContainer;
41
```
42

43
## Basic Usage
44

45
```java
46
import jakarta.enterprise.context.ApplicationScoped;
47
import jakarta.inject.Inject;
48
import io.quarkus.arc.profile.IfBuildProfile;
49
import io.quarkus.arc.log.LoggerName;
50
import org.jboss.logging.Logger;
51

52
// Conditional bean based on build profile
53
@ApplicationScoped
54
@IfBuildProfile("dev")
55
public class DevService {
56
    
57
    @Inject
58
    @LoggerName("dev.service")
59
    Logger logger;
60
    
61
    public void process() {
62
        logger.info("Processing in development mode");
63
    }
64
}
65

66
// Property-based conditional bean
67
@ApplicationScoped
68
@IfBuildProperty(name = "feature.enabled", stringValue = "true")
69
public class FeatureService {
70
    
71
    public void execute() {
72
        // Feature implementation
73
    }
74
}
75

76
// Runtime bean container access
77
@ApplicationScoped
78
public class ContainerManager {
79
    
80
    public void demonstrateContainerAccess() {
81
        // Access the bean container
82
        BeanContainer container = Arc.container();
83
        DevService service = container.beanInstance(DevService.class);
84
        service.process();
85
    }
86
}
87
```
88

89
## Architecture
90

91
Quarkus Arc is built around several key components:
92

93
- **Build-Time Processing**: CDI bean discovery and dependency resolution happens at build time, creating optimized dependency injection code
94
- **Conditional Bean Support**: Rich annotation system for enabling/disabling beans based on build profiles, properties, and runtime conditions
95
- **Context Management**: Automatic management of CDI contexts (request, application scopes) with manual control capabilities
96
- **Runtime Container**: Lightweight runtime container providing programmatic bean access and lifecycle management
97
- **Integration Layer**: Deep integration with Quarkus configuration system and MicroProfile specifications
98

99
## Capabilities
100

101
### Build Profile Conditional Beans
102

103
Control bean activation based on Quarkus build profiles, enabling different implementations for development, testing, and production environments.
104

105
```java { .api }
106
@Retention(RetentionPolicy.RUNTIME)
107
@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
108
public @interface IfBuildProfile {
109
    String value() default "";
110
    String[] allOf() default {};
111
    String[] anyOf() default {};
112
}
113

114
@Retention(RetentionPolicy.RUNTIME)
115
@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
116
public @interface UnlessBuildProfile {
117
    String value() default "";
118
    String[] allOf() default {};
119
    String[] anyOf() default {};
120
}
121
```
122

123
[Build Profile Conditionals](./build-profiles.md)
124

125
### Build Property Conditional Beans
126

127
Enable beans based on build-time configuration properties, allowing feature toggles and environment-specific configurations.
128

129
```java { .api }
130
@Repeatable(IfBuildProperty.List.class)
131
@Retention(RetentionPolicy.RUNTIME)
132
@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
133
public @interface IfBuildProperty {
134
    String name();
135
    String stringValue();
136
    boolean enableIfMissing() default false;
137
}
138

139
@Repeatable(UnlessBuildProperty.List.class)
140
@Retention(RetentionPolicy.RUNTIME)
141
@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
142
public @interface UnlessBuildProperty {
143
    String name();
144
    String stringValue();
145
    boolean enableIfMissing() default false;
146
}
147
```
148

149
[Build Property Conditionals](./build-properties.md)
150

151
### Runtime Lookup Conditionals
152

153
Control which beans are available for programmatic lookup based on runtime properties, enabling dynamic behavior without bean activation overhead.
154

155
```java { .api }
156
@Repeatable(LookupIfProperty.List.class)
157
@Retention(RetentionPolicy.RUNTIME)
158
@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
159
public @interface LookupIfProperty {
160
    String name();
161
    String stringValue();
162
    boolean lookupIfMissing() default false;
163
}
164

165
@Repeatable(LookupUnlessProperty.List.class)
166
@Retention(RetentionPolicy.RUNTIME)
167
@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
168
public @interface LookupUnlessProperty {
169
    String name();
170
    String stringValue();
171
    boolean lookupIfMissing() default false;
172
}
173
```
174

175
[Runtime Lookup Conditionals](./runtime-lookup.md)
176

177
### Logger Injection
178

179
CDI-based logger injection with support for custom logger names and automatic bean-specific logger creation.
180

181
```java { .api }
182
@Qualifier
183
@Retention(RetentionPolicy.RUNTIME)
184
@Target({ ElementType.FIELD, ElementType.PARAMETER, ElementType.METHOD })
185
public @interface LoggerName {
186
    String value();
187
    
188
    public static final class Literal extends AnnotationLiteral<LoggerName> implements LoggerName {
189
        public Literal(String value);
190
        public String value();
191
    }
192
}
193
```
194

195
[Logger Injection](./logger-injection.md)
196

197
### Bean Container Management
198

199
Programmatic access to the CDI bean container for runtime bean resolution, context management, and lifecycle control.
200

201
```java { .api }
202
public interface BeanContainer {
203
    <T> T beanInstance(Class<T> beanType, Annotation... beanQualifiers);
204
    <T> Factory<T> beanInstanceFactory(Class<T> type, Annotation... qualifiers);
205
    <T> Factory<T> beanInstanceFactory(Supplier<Factory<T>> fallbackSupplier, Class<T> type, Annotation... qualifiers);
206
    ManagedContext requestContext();
207
    
208
    interface Factory<T> {
209
        Instance<T> create();
210
    }
211
    
212
    interface Instance<T> extends AutoCloseable {
213
        T get();
214
        default void close();
215
    }
216
}
217

218
public interface BeanContainerListener {
219
    void created(BeanContainer container);
220
}
221
```
222

223
[Bean Container Management](./bean-container.md)
224

225
### Bean Invocation Utilities
226

227
Utility interfaces for invoking bean methods with automatic context management and lookup operations.
228

229
```java { .api }
230
public interface BeanInvoker<T> {
231
    default void invoke(T param) throws Exception;
232
    void invokeBean(T param) throws Exception;
233
}
234

235
public class BeanLookupSupplier implements Supplier<Object> {
236
    public BeanLookupSupplier();
237
    public BeanLookupSupplier(Class<?> type);
238
    public Class<?> getType();
239
    public BeanLookupSupplier setType(Class<?> type);
240
    public Object get();
241
}
242
```
243

244
[Bean Invocation Utilities](./bean-invocation.md)
245

246
### Interceptor Integration
247

248
Utilities for working with interceptor bindings and context data within interceptor implementations.
249

250
```java { .api }
251
public final class InterceptorBindings {
252
    public static Set<Annotation> getInterceptorBindings(InvocationContext invocationContext);
253
    public static Set<AbstractAnnotationLiteral> getInterceptorBindingLiterals(InvocationContext invocationContext);
254
}
255
```
256

257
[Interceptor Integration](./interceptor-integration.md)