0
# Configuration Management
1

2
Comprehensive system for modifying Karaf configuration files during test setup. This capability provides fine-grained control over Karaf's configuration files, supporting put, extend, and replace operations with both string-based paths and type-safe configuration pointers.
3

4
## Capabilities
5

6
### Configuration File Put Operations
7

8
Add or replace configuration values in Karaf configuration files. Put operations will either add new keys or overwrite existing values.
9

10
```java { .api }
11
/**
12
 * Put/replace a configuration value using file path and key
13
 * @param configurationFilePath Path to configuration file relative to karaf.home
14
 * @param key Configuration property key
15
 * @param value Configuration property value
16
 * @return Configuration option
17
 */
18
public static Option editConfigurationFilePut(String configurationFilePath, String key, Object value);
19

20
/**
21
 * Put/replace a configuration value using a type-safe pointer
22
 * @param configurationPointer Reference to configuration file and key
23
 * @param value Configuration property value  
24
 * @return Configuration option
25
 */
26
public static Option editConfigurationFilePut(ConfigurationPointer configurationPointer, Object value);
27

28
/**
29
 * Put multiple configuration values from a properties file
30
 * @param configurationFilePath Path to target configuration file
31
 * @param source Properties file containing values to put
32
 * @param keysToUseFromSource Specific keys to use (all keys if not specified)
33
 * @return Array of configuration options
34
 */
35
public static Option[] editConfigurationFilePut(String configurationFilePath, File source, String... keysToUseFromSource);
36
```
37

38
**Usage Examples:**
39

40
```java
41
import static org.ops4j.pax.exam.karaf.options.KarafDistributionOption.*;
42
import org.ops4j.pax.exam.karaf.options.configs.ManagementCfg;
43

44
// Put using string paths
45
Option jmxPort = editConfigurationFilePut(
46
    "etc/org.apache.karaf.management.cfg", 
47
    "rmiRegistryPort", 
48
    "1099"
49
);
50

51
// Put using type-safe pointers
52
Option jmxPortSafe = editConfigurationFilePut(
53
    ManagementCfg.RMI_REGISTRY_PORT, 
54
    "1099"
55
);
56

57
// Put from properties file
58
File configSource = new File("test-config.properties");
59
Option[] multipleConfigs = editConfigurationFilePut(
60
    "etc/system.properties",
61
    configSource,
62
    "karaf.name", "org.osgi.framework.bootdelegation"
63
);
64
```
65

66
### Configuration File Extend Operations
67

68
Extend existing configuration values rather than replacing them. Extend operations append to existing values (e.g., "a=b" becomes "a=b,c").
69

70
```java { .api }
71
/**
72
 * Extend a configuration value using file path and key
73
 * @param configurationFilePath Path to configuration file relative to karaf.home
74
 * @param key Configuration property key
75
 * @param value Value to append to existing configuration
76
 * @return Configuration option
77
 */
78
public static Option editConfigurationFileExtend(String configurationFilePath, String key, Object value);
79

80
/**
81
 * Extend a configuration value using a type-safe pointer
82
 * @param configurationPointer Reference to configuration file and key
83
 * @param value Value to append to existing configuration
84
 * @return Configuration option
85
 */
86
public static Option editConfigurationFileExtend(ConfigurationPointer configurationPointer, Object value);
87

88
/**
89
 * Extend multiple configuration values from a properties file
90
 * @param configurationFilePath Path to target configuration file
91
 * @param source Properties file containing values to extend
92
 * @param keysToUseFromSource Specific keys to use (all keys if not specified)
93
 * @return Array of configuration options
94
 */
95
public static Option[] editConfigurationFileExtend(String configurationFilePath, File source, String... keysToUseFromSource);
96
```
97

98
**Usage Examples:**
99

100
```java
101
import org.ops4j.pax.exam.karaf.options.configs.CustomProperties;
102

103
// Extend system packages
104
Option extendSystemPackages = editConfigurationFileExtend(
105
    "etc/config.properties",
106
    "org.osgi.framework.system.packages.extra",
107
    "com.example.api,com.example.util"
108
);
109

110
// Extend using type-safe pointer
111
Option extendSystemPackagesSafe = editConfigurationFileExtend(
112
    CustomProperties.SYSTEM_PACKAGES_EXTRA,
113
    "com.example.api,com.example.util"
114
);
115

116
// Extend boot delegation
117
Option extendBootDelegation = editConfigurationFileExtend(
118
    CustomProperties.BOOTDELEGATION,
119
    "sun.*,com.sun.*"
120
);
121
```
122

123
### Configuration File Replacement
124

125
Replace entire configuration files with custom versions during test setup.
126

127
```java { .api }
128
/**
129
 * Replace an entire configuration file with a custom version
130
 * @param configurationFilePath Path to configuration file to replace
131
 * @param source File containing replacement content
132
 * @return Configuration option
133
 */
134
public static Option replaceConfigurationFile(String configurationFilePath, File source);
135
```
136

137
**Usage Examples:**
138

139
```java
140
// Replace logging configuration
141
File customLoggingConfig = new File("src/test/resources/custom-logging.cfg");
142
Option replaceLogging = replaceConfigurationFile(
143
    "etc/org.ops4j.pax.logging.cfg",
144
    customLoggingConfig
145
);
146

147
// Replace system properties
148
File customSystemProps = new File("src/test/resources/system.properties");
149
Option replaceSystemProps = replaceConfigurationFile(
150
    "etc/system.properties",
151
    customSystemProps
152
);
153
```
154

155
### Configuration File Options
156

157
Implementation classes for configuration file modifications.
158

159
```java { .api }
160
/**
161
 * Abstract base class for configuration file modifications
162
 */
163
abstract class KarafDistributionConfigurationFileOption implements Option {
164
    
165
    public KarafDistributionConfigurationFileOption(ConfigurationPointer pointer, Object value);
166
    public KarafDistributionConfigurationFileOption(String configurationFilePath, String key, Object value);
167
    public KarafDistributionConfigurationFileOption(String configurationFilePath);
168
    
169
    public String getConfigurationFilePath();
170
    public String getKey();
171
    public Object getValue();
172
}
173

174
/**
175
 * Put/replace configuration file operation
176
 */
177
class KarafDistributionConfigurationFilePutOption extends KarafDistributionConfigurationFileOption {
178
    
179
    public KarafDistributionConfigurationFilePutOption(String configurationFilePath, String key, Object value);
180
    public KarafDistributionConfigurationFilePutOption(ConfigurationPointer pointer, Object value);
181
}
182

183
/**
184
 * Extend configuration file operation  
185
 */
186
class KarafDistributionConfigurationFileExtendOption extends KarafDistributionConfigurationFileOption {
187
    
188
    public KarafDistributionConfigurationFileExtendOption(String configurationFilePath, String key, Object value);
189
    public KarafDistributionConfigurationFileExtendOption(ConfigurationPointer pointer, Object value);
190
}
191

192
/**
193
 * Replace configuration file operation
194
 */
195
class KarafDistributionConfigurationFileReplacementOption extends KarafDistributionConfigurationFileOption {
196
    
197
    public KarafDistributionConfigurationFileReplacementOption(String configurationFilePath, File source);
198
    public File getSource();
199
}
200
```
201

202
## Type-Safe Configuration Pointers
203

204
Pre-defined configuration pointers for common Karaf configuration files, providing type safety and avoiding magic strings.
205

206
```java { .api }
207
/**
208
 * Type-safe reference to configuration file and key
209
 */
210
class ConfigurationPointer {
211
    
212
    public ConfigurationPointer(String configurationFilePath, String key);
213
    public String getConfigurationFilePath();
214
    public String getKey();
215
}
216
```
217

218
### Available Configuration Pointers
219

220
**CustomProperties** - etc/config.properties:
221
```java { .api }
222
class CustomProperties {
223
    public static final String FILE_PATH = "etc/config.properties";
224
    public static final ConfigurationPointer KARAF_FRAMEWORK; // Framework type (felix/equinox)
225
    public static final ConfigurationPointer SYSTEM_PACKAGES_EXTRA; // System packages extra
226
    public static final ConfigurationPointer BOOTDELEGATION; // Boot delegation packages
227
}
228
```
229

230
**FeaturesCfg** - etc/org.apache.karaf.features.cfg:
231
```java { .api }
232
class FeaturesCfg {
233
    public static final String FILE_PATH = "etc/org.apache.karaf.features.cfg";
234
    public static final ConfigurationPointer REPOSITORIES; // Features repositories list
235
    public static final ConfigurationPointer BOOT; // Features to install at boot
236
}
237
```
238

239
**LoggingCfg** - etc/org.ops4j.pax.logging.cfg:
240
```java { .api }
241
class LoggingCfg {
242
    public static final String FILE_PATH = "etc/org.ops4j.pax.logging.cfg";
243
    public static final ConfigurationPointer ROOT_LOGGER; // Root logger configuration
244
}
245
```
246

247
**ManagementCfg** - etc/org.apache.karaf.management.cfg:
248
```java { .api }
249
class ManagementCfg {
250
    public static final String FILE_PATH = "etc/org.apache.karaf.management.cfg";
251
    public static final ConfigurationPointer RMI_REGISTRY_PORT; // RMI registry port
252
    public static final ConfigurationPointer RMI_SERVER_PORT; // RMI server port
253
}
254
```
255

256
**SystemProperties** - etc/system.properties:
257
```java { .api }
258
class SystemProperties {
259
    public static final String FILE_PATH = "etc/system.properties";
260
    public static final ConfigurationPointer KARAF_NAME; // Karaf instance name
261
}
262
```
263

264
**UsersProperties** - etc/users.properties:
265
```java { .api }
266
class UsersProperties {
267
    public static final String FILE_PATH = "etc/users.properties";
268
    public static final ConfigurationPointer KARAF_USER; // Default karaf user
269
}
270
```
271

272
**WebCfg** - etc/org.ops4j.pax.web.cfg:
273
```java { .api }
274
class WebCfg {
275
    public static final String FILE_PATH = "etc/org.ops4j.pax.web.cfg";
276
    public static final ConfigurationPointer HTTP_PORT; // HTTP service port
277
}
278
```
279

280
**JreProperties** - etc/jre.properties:
281
```java { .api }
282
class JreProperties {
283
    public static final String FILE_PATH = "etc/jre.properties";
284
}
285
```
286

287
## Usage Patterns
288

289
### Combining Operations
290

291
```java
292
@Configuration
293
public Option[] config() {
294
    return new Option[] {
295
        karafDistributionConfiguration(),
296
        
297
        // Set JMX ports
298
        editConfigurationFilePut(ManagementCfg.RMI_REGISTRY_PORT, "1099"),
299
        editConfigurationFilePut(ManagementCfg.RMI_SERVER_PORT, "44444"),
300
        
301
        // Extend system packages
302
        editConfigurationFileExtend(
303
            CustomProperties.SYSTEM_PACKAGES_EXTRA,
304
            "com.example.api,com.example.util"
305
        ),
306
        
307
        // Replace logging configuration
308
        replaceConfigurationFile(
309
            "etc/org.ops4j.pax.logging.cfg",
310
            new File("src/test/resources/test-logging.cfg")
311
        )
312
    };
313
}
314
```
315

316
### Properties File Loading
317

318
```java
319
// Load multiple configurations from properties file
320
File testConfig = new File("src/test/resources/test.properties");
321
Option[] systemConfigs = editConfigurationFilePut(
322
    "etc/system.properties",
323
    testConfig,
324
    "karaf.name", "karaf.base", "java.protocol.handler.pkgs"
325
);
326
```
327

328
## Error Handling
329

330
Configuration file operations throw `IllegalStateException` for:
331
- Invalid configuration file paths
332
- Inaccessible source files for replacement
333
- Properties file parsing errors
334
- Missing configuration directories during test execution