0
# Configuration System
1

2
The Configuration System provides comprehensive configuration management with annotations, type converters, and runtime configuration support for Quarkus applications.
3

4
## Configuration Annotations
5

6
### Configuration Root
7

8
```java { .api }
9
@Retention(RetentionPolicy.RUNTIME)
10
@Target(ElementType.TYPE)
11
public @interface ConfigRoot {
12
    /**
13
     * Configuration phase when this root is available.
14
     * @return Configuration phase
15
     */
16
    ConfigPhase phase() default ConfigPhase.RUNTIME_INIT;
17
    
18
    /**
19
     * Configuration prefix (deprecated).
20
     * @return Configuration prefix
21
     */
22
    @Deprecated
23
    String prefix() default "";
24
    
25
    /**
26
     * Configuration name (deprecated).
27
     * @return Configuration name
28
     */
29
    @Deprecated
30
    String name() default "";
31
}
32
```
33

34
### Configuration Item
35

36
```java { .api }
37
@Retention(RetentionPolicy.RUNTIME)
38
@Target({ElementType.FIELD, ElementType.METHOD})
39
public @interface ConfigItem {
40
    /**
41
     * Property name override.
42
     * @return Property name, empty string uses field name
43
     */
44
    String name() default "";
45
    
46
    /**
47
     * Default value for the configuration property.
48
     * @return Default value
49
     */
50
    String defaultValue() default "";
51
    
52
    /**
53
     * Whether to include this item in generated documentation.
54
     * @return true to include in docs
55
     */
56
    boolean generateDocumentation() default true;
57
}
58
```
59

60
### Configuration Group
61

62
```java { .api }
63
@Retention(RetentionPolicy.RUNTIME)
64
@Target(ElementType.TYPE)
65
public @interface ConfigGroup {
66
    // Groups related configuration items together
67
}
68
```
69

70
## Configuration Phases
71

72
```java { .api }
73
public enum ConfigPhase {
74
    /**
75
     * Available at build time only.
76
     */
77
    BUILD_TIME,
78
    
79
    /**
80
     * Available at runtime initialization.
81
     */
82
    RUNTIME_INIT,
83
    
84
    /**
85
     * Available during bootstrap phase.
86
     */
87
    BOOTSTRAP
88
}
89
```
90

91
## Type Converters
92

93
### Duration Converter
94

95
```java { .api }
96
public class DurationConverter implements Converter<Duration> {
97
    /**
98
     * Convert string to Duration.
99
     * Supports formats like: "10s", "5m", "2h", "1d"
100
     * @param value String representation
101
     * @return Duration object
102
     */
103
    @Override
104
    public Duration convert(String value) throws IllegalArgumentException, NullPointerException;
105
}
106
```
107

108
### Memory Size Types
109

110
```java { .api }
111
public final class MemorySize {
112
    /**
113
     * Create MemorySize from bytes.
114
     * @param bytes Size in bytes
115
     */
116
    public MemorySize(long bytes);
117
    
118
    /**
119
     * Get size in bytes.
120
     * @return Size in bytes
121
     */
122
    public long getBytes();
123
    
124
    /**
125
     * Parse memory size from string.
126
     * Supports formats like: "10MB", "512KB", "2GB"
127
     * @param input String representation
128
     * @return MemorySize object
129
     */
130
    public static MemorySize parse(String input);
131
    
132
    /**
133
     * String representation in bytes.
134
     * @return String representation
135
     */
136
    public String toString();
137
    
138
    /**
139
     * Human-readable string representation.
140
     * @return Human-readable format
141
     */
142
    public String toHumanReadableString();
143
}
144

145
public class MemorySizeConverter implements Converter<MemorySize> {
146
    /**
147
     * Convert string to MemorySize.
148
     * @param value String representation (e.g., "10MB", "512KB")
149
     * @return MemorySize object
150
     */
151
    @Override
152
    public MemorySize convert(String value) throws IllegalArgumentException, NullPointerException;
153
}
154
```
155

156
### Path Converter
157

158
```java { .api }
159
public class PathConverter implements Converter<Path> {
160
    /**
161
     * Convert string to Path.
162
     * @param value String path representation
163
     * @return Path object
164
     */
165
    @Override
166
    public Path convert(String value) throws IllegalArgumentException, NullPointerException;
167
}
168
```
169

170
### Network Address Converter
171

172
```java { .api }
173
public class InetAddressConverter implements Converter<InetAddress> {
174
    /**
175
     * Convert string to InetAddress.
176
     * @param value IP address or hostname
177
     * @return InetAddress object
178
     */
179
    @Override
180
    public InetAddress convert(String value) throws IllegalArgumentException, NullPointerException;
181
}
182
```
183

184
## Configuration Exception
185

186
```java { .api }
187
public class ConfigurationException extends RuntimeException {
188
    /**
189
     * Create configuration exception with message.
190
     * @param message Error message
191
     */
192
    public ConfigurationException(String message);
193
    
194
    /**
195
     * Create configuration exception with message and cause.
196
     * @param message Error message
197
     * @param cause Root cause
198
     */
199
    public ConfigurationException(String message, Throwable cause);
200
}
201
```
202

203
## Usage Examples
204

205
### Basic Configuration Root
206

207
```java
208
import io.quarkus.runtime.annotations.ConfigRoot;
209
import io.quarkus.runtime.annotations.ConfigItem;
210
import io.quarkus.runtime.annotations.ConfigPhase;
211

212
@ConfigRoot(phase = ConfigPhase.RUNTIME_INIT)
213
public class DatabaseConfig {
214
    
215
    /**
216
     * Database URL.
217
     */
218
    @ConfigItem(defaultValue = "jdbc:h2:mem:test")
219
    public String url;
220
    
221
    /**
222
     * Database username.
223
     */
224
    @ConfigItem(defaultValue = "sa")
225
    public String username;
226
    
227
    /**
228
     * Database password.
229
     */
230
    @ConfigItem
231
    public String password;
232
    
233
    /**
234
     * Maximum pool size.
235
     */
236
    @ConfigItem(defaultValue = "10")
237
    public int maxPoolSize;
238
    
239
    /**
240
     * Connection timeout.
241
     */
242
    @ConfigItem(defaultValue = "30s")
243
    public Duration connectionTimeout;
244
}
245
```
246

247
Configuration properties (application.properties):
248
```properties
249
database.url=jdbc:postgresql://localhost:5432/mydb
250
database.username=user
251
database.password=secret
252
database.max-pool-size=20
253
database.connection-timeout=45s
254
```
255

256
### Configuration with Groups
257

258
```java
259
import io.quarkus.runtime.annotations.ConfigGroup;
260
import io.quarkus.runtime.annotations.ConfigItem;
261
import io.quarkus.runtime.annotations.ConfigRoot;
262
import io.quarkus.runtime.annotations.ConfigPhase;
263

264
@ConfigRoot(phase = ConfigPhase.RUNTIME_INIT)
265
public class ServerConfig {
266
    
267
    /**
268
     * HTTP server configuration.
269
     */
270
    @ConfigItem
271
    public HttpConfig http;
272
    
273
    /**
274
     * SSL configuration.
275
     */
276
    @ConfigItem
277
    public SslConfig ssl;
278
}
279

280
@ConfigGroup
281
public static class HttpConfig {
282
    
283
    /**
284
     * HTTP port.
285
     */
286
    @ConfigItem(defaultValue = "8080")
287
    public int port;
288
    
289
    /**
290
     * HTTP host.
291
     */
292
    @ConfigItem(defaultValue = "localhost")
293
    public String host;
294
    
295
    /**
296
     * Request timeout.
297
     */
298
    @ConfigItem(defaultValue = "30s")
299
    public Duration timeout;
300
}
301

302
@ConfigGroup
303
public static class SslConfig {
304
    
305
    /**
306
     * Enable SSL.
307
     */
308
    @ConfigItem(defaultValue = "false")
309
    public boolean enabled;
310
    
311
    /**
312
     * SSL port.
313
     */
314
    @ConfigItem(defaultValue = "8443")
315
    public int port;
316
    
317
    /**
318
     * Keystore path.
319
     */
320
    @ConfigItem
321
    public Optional<Path> keystore;
322
}
323
```
324

325
Configuration properties:
326
```properties
327
server.http.port=9090
328
server.http.host=0.0.0.0
329
server.http.timeout=60s
330
server.ssl.enabled=true
331
server.ssl.port=9443
332
server.ssl.keystore=/path/to/keystore.p12
333
```
334

335
### Custom Type Converters
336

337
```java
338
import java.util.regex.Pattern;
339
import org.eclipse.microprofile.config.spi.Converter;
340

341
// Custom converter for email addresses
342
public class EmailConverter implements Converter<Email> {
343
    private static final Pattern EMAIL_PATTERN = 
344
        Pattern.compile("^[A-Za-z0-9+_.-]+@([A-Za-z0-9.-]+\\.[A-Za-z]{2,})$");
345
    
346
    @Override
347
    public Email convert(String value) {
348
        if (value == null || value.trim().isEmpty()) {
349
            return null;
350
        }
351
        
352
        if (!EMAIL_PATTERN.matcher(value).matches()) {
353
            throw new IllegalArgumentException("Invalid email format: " + value);
354
        }
355
        
356
        return new Email(value);
357
    }
358
}
359

360
// Email type
361
public class Email {
362
    private final String address;
363
    
364
    public Email(String address) {
365
        this.address = address;
366
    }
367
    
368
    public String getAddress() {
369
        return address;
370
    }
371
    
372
    @Override
373
    public String toString() {
374
        return address;
375
    }
376
}
377

378
// Configuration using custom converter
379
@ConfigRoot(phase = ConfigPhase.RUNTIME_INIT)
380
public class NotificationConfig {
381
    
382
    /**
383
     * Admin email address.
384
     */
385
    @ConfigItem(defaultValue = "admin@example.com")
386
    public Email adminEmail;
387
    
388
    /**
389
     * Support email address.
390
     */
391
    @ConfigItem
392
    public Optional<Email> supportEmail;
393
}
394
```
395

396
### Memory Size Configuration
397

398
```java
399
import io.quarkus.runtime.configuration.MemorySize;
400

401
@ConfigRoot(phase = ConfigPhase.RUNTIME_INIT)
402
public class CacheConfig {
403
    
404
    /**
405
     * Maximum cache size.
406
     */
407
    @ConfigItem(defaultValue = "64MB")
408
    public MemorySize maxSize;
409
    
410
    /**
411
     * Initial cache size.
412
     */
413
    @ConfigItem(defaultValue = "8MB")
414
    public MemorySize initialSize;
415
}
416
```
417

418
Configuration properties:
419
```properties
420
cache.max-size=128MB
421
cache.initial-size=16MB
422
```
423

424
Usage:
425
```java
426
@Inject
427
CacheConfig cacheConfig;
428

429
public void setupCache() {
430
    long maxBytes = cacheConfig.maxSize.getBytes();
431
    long initialBytes = cacheConfig.initialSize.getBytes();
432
    
433
    System.out.println("Max cache size: " + cacheConfig.maxSize.toHumanReadableString());
434
    System.out.println("Initial cache size: " + cacheConfig.initialSize.toHumanReadableString());
435
}
436
```
437

438
### Build-Time Configuration
439

440
```java
441
@ConfigRoot(phase = ConfigPhase.BUILD_TIME)
442
public class BuildTimeConfig {
443
    
444
    /**
445
     * Enable debug information in build.
446
     */
447
    @ConfigItem(defaultValue = "false")
448
    public boolean debug;
449
    
450
    /**
451
     * Build optimization level.
452
     */
453
    @ConfigItem(defaultValue = "O2")
454
    public String optimizationLevel;
455
    
456
    /**
457
     * Build artifacts directory.
458
     */
459
    @ConfigItem(defaultValue = "target")
460
    public Path artifactsDir;
461
}
462
```
463

464
### Configuration Injection
465

466
```java
467
import jakarta.enterprise.context.ApplicationScoped;
468
import jakarta.inject.Inject;
469

470
@ApplicationScoped
471
public class DatabaseService {
472
    
473
    @Inject
474
    DatabaseConfig config;
475
    
476
    public void connect() {
477
        try {
478
            Connection connection = DriverManager.getConnection(
479
                config.url, 
480
                config.username, 
481
                config.password
482
            );
483
            
484
            // Configure connection pool
485
            configurePool(connection, config.maxPoolSize, config.connectionTimeout);
486
            
487
        } catch (SQLException e) {
488
            throw new ConfigurationException("Failed to connect to database", e);
489
        }
490
    }
491
    
492
    private void configurePool(Connection connection, int maxSize, Duration timeout) {
493
        // Pool configuration logic
494
    }
495
}
496
```
497

498
## Configuration Profiles
499

500
Configuration can vary by profile (dev, test, prod):
501

502
```properties
503
# Default configuration
504
server.port=8080
505
database.url=jdbc:h2:mem:test
506

507
# Development profile
508
%dev.server.port=8081
509
%dev.database.url=jdbc:h2:mem:dev
510

511
# Test profile  
512
%test.server.port=0
513
%test.database.url=jdbc:h2:mem:test
514

515
# Production profile
516
%prod.server.port=80
517
%prod.database.url=jdbc:postgresql://prod-db:5432/app
518
```
519

520
Access current profile:
521
```java
522
import io.quarkus.runtime.LaunchMode;
523

524
LaunchMode mode = LaunchMode.current();
525
String profile = mode.getDefaultProfile(); // "dev", "test", or "prod"
526
```