0
# Runtime Configuration
1

2
Control over Karaf container runtime behavior including logging, debugging, console access, directory management, and system-level configuration. This capability provides essential options for test execution control and debugging support.
3

4
## Capabilities
5

6
### Runtime Folder Management
7

8
Control whether test runtime directories are preserved after test completion for debugging purposes.
9

10
```java { .api }
11
/**
12
 * Keep test runtime directories after test completion
13
 * By default, Pax Exam deletes test directories after tests finish
14
 * @return Option to preserve runtime directories
15
 */
16
public static Option keepRuntimeFolder();
17
```
18

19
**Usage Examples:**
20

21
```java
22
import static org.ops4j.pax.exam.karaf.options.KarafDistributionOption.*;
23

24
@Configuration
25
public Option[] config() {
26
    return new Option[] {
27
        karafDistributionConfiguration(),
28
        
29
        // Keep directories for debugging
30
        keepRuntimeFolder(),
31
        
32
        // Other configuration...
33
    };
34
}
35
```
36

37
### Logging Configuration
38

39
Configure logging levels and behavior for the test container.
40

41
```java { .api }
42
/**
43
 * Set a specific log level for the container
44
 * @param logLevel Log level to set
45
 * @return Logging configuration option
46
 */
47
public static Option logLevel(LogLevel logLevel);
48

49
/**
50
 * Get a log level option builder for advanced configuration
51
 * @return LogLevelOption for fluent configuration
52
 */
53
public static LogLevelOption logLevel();
54

55
/**
56
 * Prevent automatic modification of log configuration files
57
 * By default, Pax Exam modifies logging configuration to add console output
58
 * @return Option to preserve original log configuration
59
 */
60
public static Option doNotModifyLogConfiguration();
61
```
62

63
**Usage Examples:**
64

65
```java
66
import org.ops4j.pax.exam.karaf.options.LogLevelOption.LogLevel;
67

68
// Set specific log level
69
Option infoLogging = logLevel(LogLevel.INFO);
70
Option debugLogging = logLevel(LogLevel.DEBUG);
71
Option errorLogging = logLevel(LogLevel.ERROR);
72

73
// Use fluent configuration
74
Option fluentLogging = logLevel().logLevel(LogLevel.WARN);
75

76
// Prevent automatic log configuration changes
77
Option preserveLogging = doNotModifyLogConfiguration();
78

79
// Complete configuration
80
@Configuration
81
public Option[] config() {
82
    return new Option[] {
83
        karafDistributionConfiguration(),
84
        logLevel(LogLevel.DEBUG),
85
        doNotModifyLogConfiguration(), // Keep original log config
86
        keepRuntimeFolder()
87
    };
88
}
89
```
90

91
### Debug Configuration
92

93
Enable remote debugging support for the Karaf container to allow IDE attachment and debugging.
94

95
```java { .api }
96
/**
97
 * Enable debugging with default port 5005 and suspend VM until debugger attaches
98
 * @return Debug configuration option
99
 */
100
public static Option debugConfiguration();
101

102
/**
103
 * Enable debugging with custom port and suspend behavior
104
 * @param port Debug port number
105
 * @param hold Whether to suspend VM until debugger attaches
106
 * @return Debug configuration option
107
 */
108
public static Option debugConfiguration(String port, boolean hold);
109
```
110

111
**Usage Examples:**
112

113
```java
114
// Default debug configuration (port 5005, suspend=true)
115
Option defaultDebug = debugConfiguration();
116

117
// Custom debug port without suspending 
118
Option customDebug = debugConfiguration("8000", false);
119

120
// Debug with suspend for IDE attachment
121
Option suspendDebug = debugConfiguration("5005", true);
122

123
// Debug configuration in test
124
@Configuration
125
public Option[] config() {
126
    return new Option[] {
127
        karafDistributionConfiguration(),
128
        debugConfiguration("8000", false), // Debug on port 8000, don't suspend
129
        keepRuntimeFolder() // Keep for debugging
130
    };
131
}
132
```
133

134
### System Configuration
135

136
Configure internal Pax Exam system behavior and bundle start levels.
137

138
```java { .api }
139
/**
140
 * Configure the internal invoker for Karaf integration tests
141
 * @param invoker Probe invoker name for integration test communication
142
 * @return System configuration option
143
 */
144
public static Option useOwnKarafExamSystemConfiguration(String invoker);
145

146
/**
147
 * Configure start level for Pax Exam bundles
148
 * @param startLevel Bundle start level for exam bundles
149
 * @return Start level configuration option
150
 */
151
public static Option useOwnExamBundlesStartLevel(int startLevel);
152
```
153

154
**Usage Examples:**
155

156
```java
157
// Configure custom invoker
158
Option customInvoker = useOwnKarafExamSystemConfiguration("custom-invoker");
159

160
// Set exam bundles start level
161
Option examStartLevel = useOwnExamBundlesStartLevel(80);
162

163
// System configuration in test
164
@Configuration
165
public Option[] config() {
166
    return new Option[] {
167
        karafDistributionConfiguration(),
168
        useOwnExamBundlesStartLevel(90), // High start level for exam bundles
169
        useOwnKarafExamSystemConfiguration("test-invoker")
170
    };
171
}
172
```
173

174
## Runtime Option Types
175

176
### Keep Runtime Folder Option
177

178
Simple flag option to preserve test directories.
179

180
```java { .api }
181
/**
182
 * Option to keep runtime directories after test completion
183
 */
184
class KeepRuntimeFolderOption implements Option {
185
    
186
    public KeepRuntimeFolderOption();
187
}
188
```
189

190
### Log Level Option
191

192
Configurable logging level option with fluent interface.
193

194
```java { .api }
195
/**
196
 * Logging level configuration option
197
 */
198
class LogLevelOption implements Option {
199
    
200
    // Log level enumeration
201
    enum LogLevel {
202
        TRACE, DEBUG, INFO, WARN, ERROR
203
    }
204
    
205
    public LogLevelOption();
206
    public LogLevelOption(LogLevel logLevel);
207
    
208
    public LogLevelOption logLevel(LogLevel logLevel);
209
    public LogLevel getLogLevel();
210
}
211
```
212

213
### Do Not Modify Log Option
214

215
Flag option to prevent automatic log configuration changes.
216

217
```java { .api }
218
/**
219
 * Option to prevent automatic log configuration modifications
220
 */
221
class DoNotModifyLogOption implements Option {
222
    
223
    public DoNotModifyLogOption();
224
}
225
```
226

227
### Exam System Configuration Option
228

229
Internal system configuration for Pax Exam integration.
230

231
```java { .api }
232
/**
233
 * Configuration option for internal Pax Exam system behavior
234
 */
235
class KarafExamSystemConfigurationOption implements Option {
236
    
237
    public KarafExamSystemConfigurationOption(String invoker);
238
    public String getInvoker();
239
}
240
```
241

242
### Exam Bundles Start Level Option
243

244
Configuration for Pax Exam bundle start levels.
245

246
```java { .api }
247
/**
248
 * Start level configuration for Pax Exam bundles
249
 */
250
class ExamBundlesStartLevel implements Option {
251
    
252
    public ExamBundlesStartLevel(int startLevel);
253
    public int getStartLevel();
254
}
255
```
256

257
## Runtime Configuration Patterns
258

259
### Development Configuration
260

261
Configuration optimized for development and debugging:
262

263
```java
264
@Configuration
265
public Option[] developmentConfig() {
266
    return new Option[] {
267
        karafDistributionConfiguration()
268
            .unpackDirectory(new File("target/exam"))
269
            .useDeployFolder(true),
270
        
271
        // Development settings
272
        keepRuntimeFolder(),                    // Keep for inspection
273
        logLevel(LogLevel.DEBUG),              // Verbose logging
274
        debugConfiguration("5005", true),     // Enable debugging
275
        doNotModifyLogConfiguration(),         // Use custom log config
276
        
277
        // Install development features
278
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
279
                "ssh", "management", "webconsole")
280
    };
281
}
282
```
283

284
### Production-like Configuration
285

286
Configuration that mimics production environment:
287

288
```java
289
@Configuration  
290
public Option[] productionConfig() {
291
    return new Option[] {
292
        karafDistributionConfiguration()
293
            .runEmbedded(false)
294
            .useDeployFolder(false),
295
        
296
        // Production-like settings
297
        logLevel(LogLevel.WARN),               // Minimal logging
298
        useOwnExamBundlesStartLevel(100),      // High start level
299
        
300
        // Production features only
301
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
302
                "scr", "log")
303
    };
304
}
305
```
306

307
### Test-specific Configuration
308

309
Configuration tailored for specific test requirements:
310

311
```java
312
@Configuration
313
public Option[] integrationTestConfig() {
314
    return new Option[] {
315
        karafDistributionConfiguration()
316
            .directoryNameFormat("test-%s")
317
            .unpackDirectory(new File("target/integration-tests")),
318
        
319
        // Test-specific settings
320
        keepRuntimeFolder(),                   // For test artifact inspection
321
        logLevel(LogLevel.INFO),              // Moderate logging
322
        useOwnKarafExamSystemConfiguration("integration-invoker"),
323
        
324
        // Test features
325
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
326
                "scr", "http", "management")
327
    };
328
}
329
```
330

331
### Performance Test Configuration
332

333
Configuration optimized for performance testing:
334

335
```java
336
@Configuration
337
public Option[] performanceConfig() {
338
    return new Option[] {
339
        karafDistributionConfiguration()
340
            .runEmbedded(true)                 // Faster startup
341
            .useDeployFolder(false),           // No hot deploy overhead
342
        
343
        // Performance settings  
344
        logLevel(LogLevel.ERROR),              // Minimal logging overhead
345
        useOwnExamBundlesStartLevel(50),       // Lower start level for speed
346
        
347
        // Minimal features
348
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
349
                "scr")
350
    };
351
}
352
```
353

354
## Debugging Support
355

356
### Remote Debugging Setup
357

358
Enable remote debugging for IDE attachment:
359

360
```java
361
@Configuration
362
public Option[] debugConfig() {
363
    return new Option[] {
364
        karafDistributionConfiguration(),
365
        
366
        // Debug configuration
367
        debugConfiguration("8000", true),     // Port 8000, wait for debugger
368
        keepRuntimeFolder(),                  // Keep for debugging
369
        logLevel(LogLevel.DEBUG),             // Debug logging
370
        
371
        // SSH access for debugging
372
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
373
                "ssh", "management")
374
    };
375
}
376

377
// IDE Debug Configuration:
378
// - Host: localhost
379
// - Port: 8000  
380
// - Transport: Socket
381
// - Debugger Mode: Attach
382
```
383

384
### Log Analysis Support
385

386
Configure logging for comprehensive test analysis:
387

388
```java
389
@Configuration
390
public Option[] logAnalysisConfig() {
391
    return new Option[] {
392
        karafDistributionConfiguration(),
393
        
394
        // Preserve all test artifacts
395
        keepRuntimeFolder(),
396
        
397
        // Detailed logging without auto-modification
398
        doNotModifyLogConfiguration(),
399
        
400
        // Custom log configuration file with detailed patterns
401
        replaceConfigurationFile(
402
            "etc/org.ops4j.pax.logging.cfg",
403
            new File("src/test/resources/detailed-logging.cfg")
404
        )
405
    };
406
}
407
```
408

409
## Error Handling
410

411
Runtime configuration operations handle errors for:
412
- Invalid debug port numbers (non-numeric or out of range)
413
- Inaccessible unpack directories
414
- Invalid start level values (negative numbers)
415
- Invalid invoker names
416
- System property conflicts
417
- JVM debugging configuration conflicts
418

419
Most runtime configuration errors are detected at test startup and will cause immediate test failure with descriptive error messages.