0
# Feature Management
1

2
Installation and configuration of Karaf features from repositories during test setup. This capability enables comprehensive testing of feature-based OSGi applications by programmatically installing features and their dependencies in the test container.
3

4
## Capabilities
5

6
### Feature Installation
7

8
Install Karaf features from feature repositories during test container startup.
9

10
```java { .api }
11
/**
12
 * Install features from a repository URL
13
 * @param repositoryUrl URL to the features repository XML
14
 * @param features Names of features to install
15
 * @return Feature installation option
16
 */
17
public static KarafFeaturesOption features(String repositoryUrl, String... features);
18

19
/**
20
 * Install features using a URL reference
21
 * @param repositoryUrl URL reference to the features repository
22
 * @param features Names of features to install  
23
 * @return Feature installation option
24
 */
25
public static KarafFeaturesOption features(UrlReference repositoryUrl, String... features);
26
```
27

28
**Usage Examples:**
29

30
```java
31
import static org.ops4j.pax.exam.karaf.options.KarafDistributionOption.*;
32

33
// Install features from Maven repository
34
Option webFeatures = features(
35
    "mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
36
    "http", "jetty", "webconsole"
37
);
38

39
// Install custom features
40
Option customFeatures = features(
41
    "mvn:com.example/example-features/1.0.0/xml/features",
42
    "example-core", "example-rest"
43
);
44

45
// Install single feature
46
Option scrFeature = features(
47
    "mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
48
    "scr"
49
);
50

51
// Using file URL for local features repository
52
Option localFeatures = features(
53
    "file:///opt/features/my-features.xml",
54
    "my-feature-1", "my-feature-2"
55
);
56
```
57

58
### Features Option
59

60
Configuration option for feature installation with repository and feature management.
61

62
```java { .api }
63
/**
64
 * Feature installation option implementing both Option and UrlReference
65
 */
66
class KarafFeaturesOption implements Option, UrlReference {
67
    
68
    public KarafFeaturesOption(String repositoryUrl, String... features);
69
    public KarafFeaturesOption(UrlReference repositoryUrl, String... features);
70
    
71
    public String[] getFeatures();
72
    public String getURL(); // From UrlReference interface
73
}
74
```
75

76
**Usage Examples:**
77

78
```java
79
// Create and inspect features option
80
KarafFeaturesOption featuresOpt = features(
81
    "mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
82
    "http", "jetty"
83
);
84

85
String[] installedFeatures = featuresOpt.getFeatures(); // ["http", "jetty"]
86
String repoUrl = featuresOpt.getURL(); // Repository URL
87
```
88

89
## Common Feature Repositories
90

91
### Standard Karaf Features
92

93
Standard Apache Karaf features repository containing core OSGi and Karaf features:
94

95
```java
96
// Standard features repository URL pattern
97
String standardFeatures = "mvn:org.apache.karaf.features/standard/{karaf-version}/xml/features";
98

99
// Common standard features
100
Option commonFeatures = features(standardFeatures,
101
    "scr",              // Declarative Services
102
    "http",             // HTTP Service
103
    "jetty",            // Jetty Web Server
104
    "webconsole",       // Web Management Console
105
    "ssh",              // SSH Shell
106
    "management",       // JMX Management
107
    "scheduler",        // Scheduler Service
108
    "eventadmin",       // Event Admin Service
109
    "log",              // Logging Service
110
    "config",           // Configuration Admin
111
    "region",           // Karaf Regions
112
    "package",          // Package Admin
113
    "kar",              // Karaf Archive
114
    "wrap"              // Bundle Wrap Service
115
);
116
```
117

118
### Enterprise Features
119

120
Apache Karaf enterprise features for advanced capabilities:
121

122
```java
123
String enterpriseFeatures = "mvn:org.apache.karaf.features/enterprise/4.2.0/xml/features"; 
124

125
Option enterpriseFeatures = features(enterpriseFeatures,
126
    "transaction",      // JTA Transaction Manager
127
    "jndi",            // JNDI Service
128
    "jms",             // JMS Support
129
    "jpa",             // JPA Support
130
    "application-without-isolation", // Application deployment
131
    "obr"              // OSGi Bundle Repository
132
);
133
```
134

135
### Spring Features
136

137
Spring framework integration features:
138

139
```java
140
String springFeatures = "mvn:org.apache.karaf.features/spring/4.2.0/xml/features";
141

142
Option springFeatures = features(springFeatures,
143
    "spring",           // Spring Framework
144
    "spring-aspects",   // Spring AOP
145
    "spring-instrument", // Spring Instrumentation
146
    "spring-jdbc",      // Spring JDBC
147
    "spring-jms",       // Spring JMS
148
    "spring-struts",    // Spring Struts Integration
149
    "spring-web",       // Spring Web
150
    "spring-webmvc"     // Spring Web MVC
151
);
152
```
153

154
## Feature Installation Patterns
155

156
### Sequential Feature Installation
157

158
Install features in dependency order:
159

160
```java
161
@Configuration
162
public Option[] config() {
163
    return new Option[] {
164
        karafDistributionConfiguration(),
165
        
166
        // Install base features first
167
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
168
                "scr", "http", "log"),
169
        
170
        // Then install dependent features
171
        features("mvn:org.apache.karaf.features/enterprise/4.2.0/xml/features",
172
                "transaction", "jndi"),
173
        
174
        // Finally install application features
175
        features("mvn:com.example/app-features/1.0.0/xml/features",
176
                "app-core", "app-web")
177
    };
178
}
179
```
180

181
### Multiple Repository Installation
182

183
Install features from multiple repositories:
184

185
```java
186
@Configuration  
187
public Option[] config() {
188
    return new Option[] {
189
        karafDistributionConfiguration(),
190
        
191
        // Karaf standard features
192
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
193
                "scr", "http", "webconsole"),
194
        
195
        // Third-party features
196
        features("mvn:org.apache.cxf.karaf/apache-cxf/3.2.0/xml/features", 
197
                "cxf-core", "cxf-jaxws"),
198
        
199
        // Application features  
200
        features("mvn:com.example/example-features/1.0.0/xml/features",
201
                "example-api", "example-impl")
202
    };
203
}
204
```
205

206
### Conditional Feature Installation
207

208
Install features based on test conditions:
209

210
```java
211
private Option[] getFeatures() {
212
    List<Option> options = new ArrayList<>();
213
    
214
    // Always install base features
215
    options.add(features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
216
                        "scr", "log"));
217
    
218
    // Conditionally install web features
219
    if (isWebTest()) {
220
        options.add(features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
221
                            "http", "jetty", "webconsole"));
222
    }
223
    
224
    // Conditionally install enterprise features
225
    if (isEnterpriseTest()) {
226
        options.add(features("mvn:org.apache.karaf.features/enterprise/4.2.0/xml/features",
227
                            "transaction", "jpa"));
228
    }
229
    
230
    return options.toArray(new Option[0]);
231
}
232
```
233

234
## Feature Repository Types
235

236
### Maven Repository References
237

238
Most common pattern using Maven coordinates:
239

240
```java
241
// Standard Maven GAV pattern
242
"mvn:groupId/artifactId/version/type/classifier"
243

244
// Examples
245
"mvn:org.apache.karaf.features/standard/4.2.0/xml/features"
246
"mvn:com.example/custom-features/1.2.3/xml/features"
247
"mvn:org.apache.cxf.karaf/apache-cxf/3.2.0/xml/features"
248
```
249

250
### File URLs
251

252
Local feature repository files:
253

254
```java
255
// Absolute file path
256
"file:///opt/karaf/features/custom-features.xml"
257

258
// Relative to project
259
"file://src/test/resources/test-features.xml"
260
```
261

262
### HTTP URLs
263

264
Remote feature repositories:
265

266
```java
267
// HTTP URL
268
"http://example.com/features/my-features.xml"
269

270
// HTTPS URL  
271
"https://repository.example.com/features/enterprise-features.xml"
272
```
273

274
## Integration with Configuration
275

276
Combine feature installation with configuration management:
277

278
```java
279
@Configuration
280
public Option[] config() {
281
    return new Option[] {
282
        karafDistributionConfiguration(),
283
        
284
        // Configure feature repositories in features.cfg
285
        editConfigurationFilePut(FeaturesCfg.REPOSITORIES,
286
            "mvn:org.apache.karaf.features/standard/4.2.0/xml/features," +
287
            "mvn:com.example/example-features/1.0.0/xml/features"),
288
        
289
        // Configure boot features
290
        editConfigurationFilePut(FeaturesCfg.BOOT,
291
            "config,ssh,management"),
292
        
293
        // Install additional features programmatically
294
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
295
                "http", "webconsole")
296
    };
297
}
298
```
299

300
## Error Handling
301

302
Feature installation operations may throw exceptions for:
303
- Invalid repository URLs
304
- Inaccessible Maven artifacts
305
- Missing feature dependencies
306
- Network connectivity issues
307
- Invalid feature names
308
- Repository parsing errors
309

310
Feature installation failures typically occur during container startup and will cause test failure with detailed error messages about missing dependencies or invalid feature definitions.