0
# Bean Container
1

2
The bean container integration provides access to the fully initialized CDI container and enables registration of container lifecycle listeners. This is the final phase of the CDI build process where the optimized container becomes available.
3

4
## Capabilities
5

6
### Container Access
7

8
Access to the fully initialized and optimized CDI bean container.
9

10
```java { .api }
11
/**
12
 * Represents the fully initialized CDI bean container
13
 */
14
public class BeanContainerBuildItem extends SimpleBuildItem {
15
    public BeanContainerBuildItem(BeanContainer value);
16
    
17
    /**
18
     * Get the initialized bean container
19
     */
20
    public BeanContainer getValue();
21
}
22

23
/**
24
 * The CDI bean container interface
25
 */
26
public interface BeanContainer {
27
    /**
28
     * Get a bean instance by type
29
     */
30
    <T> T instance(Class<T> type, Annotation... qualifiers);
31
    
32
    /**
33
     * Get a bean instance by type name
34
     */
35
    <T> T instance(String className);
36
    
37
    /**
38
     * Get all bean instances of a given type
39
     */
40
    <T> List<T> instances(Class<T> type);
41
    
42
    /**
43
     * Check if a bean of the given type exists
44
     */
45
    boolean hasBean(Class<?> type, Annotation... qualifiers);
46
    
47
    /**
48
     * Get bean metadata
49
     */
50
    <T> BeanMetadata<T> getBeanMetadata(Class<T> type, Annotation... qualifiers);
51
}
52
```
53

54
**Usage Examples:**
55

56
```java
57
// Access the bean container in a build step
58
@BuildStep
59
@Record(ExecutionTime.RUNTIME_INIT)
60
void initializeRuntime(BeanContainerBuildItem beanContainer, 
61
                      RuntimeRecorder recorder) {
62
    
63
    BeanContainer container = beanContainer.getValue();
64
    
65
    // Initialize runtime services using the container
66
    recorder.initializeServices(container);
67
}
68

69
// Use container for service lookup
70
@BuildStep
71
void configureServices(BeanContainerBuildItem beanContainer) {
72
    BeanContainer container = beanContainer.getValue();
73
    
74
    // Check if service is available
75
    if (container.hasBean(DatabaseService.class)) {
76
        DatabaseService service = container.instance(DatabaseService.class);
77
        // Configure or validate service
78
    }
79
}
80
```
81

82
### Container Listeners
83

84
Register listeners that are notified during container initialization phases.
85

86
```java { .api }
87
/**
88
 * Register listeners for bean container initialization
89
 */
90
public class BeanContainerListenerBuildItem extends MultiBuildItem {
91
    public BeanContainerListenerBuildItem(BeanContainerListener beanContainerListener);
92
    
93
    /**
94
     * Get the registered container listener
95
     */
96
    public BeanContainerListener getBeanContainerListener();
97
}
98

99
/**
100
 * Listener interface for container lifecycle events
101
 */
102
public interface BeanContainerListener {
103
    /**
104
     * Called when the bean container is created but before beans are instantiated
105
     */
106
    void created(BeanContainer container);
107
    
108
    /**
109
     * Called when the bean container is being initialized
110
     */
111
    default void beforeBeanDiscovery(BeanContainer container) {}
112
    
113
    /**
114
     * Called after bean discovery is complete
115
     */
116
    default void afterBeanDiscovery(BeanContainer container) {}
117
    
118
    /**
119
     * Called when container initialization is complete
120
     */
121
    default void initialized(BeanContainer container) {}
122
}
123
```
124

125
**Usage Examples:**
126

127
```java
128
// Register a container listener
129
@BuildStep
130
BeanContainerListenerBuildItem registerContainerListener() {
131
    return new BeanContainerListenerBuildItem(new BeanContainerListener() {
132
        @Override
133
        public void created(BeanContainer container) {
134
            // Perform initialization when container is created
135
            initializeCustomServices(container);
136
        }
137
        
138
        @Override
139
        public void initialized(BeanContainer container) {
140
            // Final initialization when container is ready
141
            validateConfiguration(container);
142
        }
143
    });
144
}
145

146
// Register multiple listeners for different phases
147
@BuildStep
148
void registerLifecycleListeners(BuildProducer<BeanContainerListenerBuildItem> listeners) {
149
    // Early initialization listener
150
    listeners.produce(new BeanContainerListenerBuildItem(container -> {
151
        // Early setup tasks
152
        setupInfrastructure(container);
153
    }));
154
    
155
    // Post-initialization listener  
156
    listeners.produce(new BeanContainerListenerBuildItem(new BeanContainerListener() {
157
        @Override
158
        public void initialized(BeanContainer container) {
159
            // Post-initialization tasks
160
            startServices(container);
161
        }
162
    }));
163
}
164
```
165

166
### Container Phases
167

168
Build items that mark different phases of container initialization.
169

170
```java { .api }
171
/**
172
 * Marker for pre-container initialization phase
173
 */
174
public class PreBeanContainerBuildItem extends SimpleBuildItem {
175
    public PreBeanContainerBuildItem(SyntheticBeansRuntimeInitBuildItem syntheticBeansRuntimeInit,
176
                                    BeanContainerBuildItem beanContainer);
177
    
178
    public SyntheticBeansRuntimeInitBuildItem getSyntheticBeansRuntimeInit();
179
    public BeanContainerBuildItem getBeanContainer();
180
}
181

182
/**
183
 * Context registration phase marker
184
 */
185
public class ContextRegistrationPhaseBuildItem extends SimpleBuildItem {
186
    public ContextRegistrationPhaseBuildItem(BeanProcessor.Builder builder);
187
    public BeanProcessor.Builder getBeanProcessor(); 
188
}
189

190
/**
191
 * Observer registration phase marker
192
 */
193
public class ObserverRegistrationPhaseBuildItem extends SimpleBuildItem {
194
    public ObserverRegistrationPhaseBuildItem(BeanProcessor.Builder builder);
195
    public BeanProcessor.Builder getBeanProcessor();
196
}
197
```
198

199
### Runtime Integration
200

201
Integration points for runtime behavior and recorder patterns.
202

203
```java { .api }
204
/**
205
 * Runtime initialization of synthetic beans
206
 */
207
public class SyntheticBeansRuntimeInitBuildItem extends SimpleBuildItem {
208
    public SyntheticBeansRuntimeInitBuildItem(RuntimeValue<BeanContainer> beanContainer);
209
    public RuntimeValue<BeanContainer> getBeanContainer();
210
}
211

212
/**
213
 * Resources generation phase marker
214
 */
215
public class ResourcesGeneratedPhaseBuildItem extends SimpleBuildItem {
216
    public ResourcesGeneratedPhaseBuildItem(Set<String> generatedResources);
217
    public Set<String> getGeneratedResources();
218
}
219
```
220

221
**Usage Examples:**
222

223
```java
224
// Handle pre-container phase
225
@BuildStep
226
void handlePreContainer(PreBeanContainerBuildItem preContainer) {
227
    BeanContainer container = preContainer.getBeanContainer().getValue();
228
    
229
    // Perform pre-initialization tasks
230
    configureCustomContexts(container);
231
}
232

233
// Register contexts during context registration phase
234
@BuildStep  
235
void registerCustomContexts(ContextRegistrationPhaseBuildItem contextPhase) {
236
    BeanProcessor.Builder builder = contextPhase.getBeanProcessor();
237
    
238
    // Register custom context implementations
239
    builder.addContext(new CustomContext());
240
}
241
```
242

243
### Container Metadata
244

245
Access to container metadata and bean information.
246

247
```java { .api }
248
/**
249
 * Bean metadata information
250
 */
251
public interface BeanMetadata<T> {
252
    /**
253
     * Get the bean class
254
     */
255
    Class<T> getBeanClass();
256
    
257
    /**
258
     * Get bean qualifiers
259
     */
260
    Set<Annotation> getQualifiers();
261
    
262
    /**
263
     * Get bean scope
264
     */
265
    Class<? extends Annotation> getScope();
266
    
267
    /**
268
     * Check if bean is alternative
269
     */
270
    boolean isAlternative();
271
    
272
    /**
273
     * Get bean name if named
274
     */
275
    Optional<String> getName();
276
}
277

278
/**
279
 * Application class predicate for determining application vs framework beans
280
 */
281
public class CompletedApplicationClassPredicateBuildItem extends SimpleBuildItem {
282
    public CompletedApplicationClassPredicateBuildItem(Predicate<String> predicate);
283
    public Predicate<String> getPredicate();
284
}
285
```
286

287
## Container Usage Patterns
288

289
### Service Initialization
290

291
```java
292
@BuildStep
293
@Record(ExecutionTime.RUNTIME_INIT) 
294
void initializeApplicationServices(BeanContainerBuildItem beanContainer,
295
                                  MyServiceRecorder recorder) {
296
    // Use the container to initialize application services
297
    recorder.initialize(beanContainer.getValue());
298
}
299
```
300

301
### Validation and Health Checks
302

303
```java
304
@BuildStep
305
BeanContainerListenerBuildItem addValidationListener() {
306
    return new BeanContainerListenerBuildItem(container -> {
307
        // Validate required services are present
308
        if (!container.hasBean(DatabaseService.class)) {
309
            throw new IllegalStateException("DatabaseService not configured");
310
        }
311
        
312
        // Perform health checks
313
        HealthService health = container.instance(HealthService.class);
314
        health.validateConfiguration();
315
    });
316
}
317
```
318

319
### Custom Context Management
320

321
```java
322
@BuildStep
323
void setupCustomContexts(ContextRegistrationPhaseBuildItem contextPhase,
324
                        BeanContainerListenerBuildItem.Builder listeners) {
325
    
326
    // Register context during registration phase
327
    contextPhase.getBeanProcessor().addContext(new TenantContext());
328
    
329
    // Add listener to initialize context
330
    listeners.produce(new BeanContainerListenerBuildItem(container -> {
331
        TenantContext context = container.instance(TenantContext.class);
332
        context.initialize();
333
    }));
334
}
335
```
336

337
The bean container represents the culmination of the CDI build process, providing access to the fully optimized and configured container that will be used at runtime.