0
# Pax Exam Container Karaf
1

2
A specialized container implementation for the Pax Exam testing framework, specifically designed for testing OSGi applications within Apache Karaf environments. This library enables developers to write integration tests that can launch, configure, and interact with Karaf instances programmatically, allowing for comprehensive testing of OSGi bundles, features, and configurations in a controlled environment.
3

4
## Package Information
5

6
- **Package Name**: pax-exam-container-karaf
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.ops4j.pax.exam</groupId>
13
    <artifactId>pax-exam-container-karaf</artifactId>
14
    <version>4.14.0</version>
15
    <scope>test</scope>
16
  </dependency>
17
  ```
18

19
## Core Imports
20

21
```java
22
import static org.ops4j.pax.exam.karaf.options.KarafDistributionOption.*;
23
import org.ops4j.pax.exam.Option;
24
import org.ops4j.pax.exam.karaf.options.KarafDistributionBaseConfigurationOption;
25
import org.ops4j.pax.exam.karaf.options.LogLevelOption.LogLevel;
26
```
27

28
## Basic Usage
29

30
```java
31
import static org.ops4j.pax.exam.CoreOptions.*;
32
import static org.ops4j.pax.exam.karaf.options.KarafDistributionOption.*;
33
import org.ops4j.pax.exam.Configuration;
34
import org.ops4j.pax.exam.Option;
35
import org.ops4j.pax.exam.junit.PaxExam;
36
import org.ops4j.pax.exam.karaf.options.LogLevelOption.LogLevel;
37
import org.junit.Test;
38
import org.junit.runner.RunWith;
39

40
@RunWith(PaxExam.class)
41
public class BasicKarafTest {
42

43
    @Configuration
44
    public Option[] config() {
45
        return new Option[] {
46
            // Configure Karaf distribution
47
            karafDistributionConfiguration()
48
                .frameworkUrl("mvn:org.apache.karaf/apache-karaf/4.2.0/zip")
49
                .karafVersion("4.2.0")
50
                .name("Apache Karaf"),
51
            
52
            // Set log level
53
            logLevel(LogLevel.INFO),
54
            
55
            // Install features
56
            features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features", 
57
                    "scr", "http"),
58
            
59
            // Keep runtime folder for debugging
60
            keepRuntimeFolder()
61
        };
62
    }
63

64
    @Test
65
    public void testKarafContainer() {
66
        // Your test logic here
67
    }
68
}
69
```
70

71
## Architecture
72

73
Pax Exam Container Karaf is built around several key components:
74

75
- **Distribution Configuration**: Setup and configuration of Karaf distributions (`KarafDistributionOption`)
76
- **Configuration File Management**: Modification of Karaf configuration files during test setup
77
- **Feature Management**: Installation and configuration of Karaf features
78
- **Runtime Control**: Control over Karaf container lifecycle and runtime behavior
79
- **Option Pattern**: Fluent configuration API using the Pax Exam Option pattern
80

81
The library integrates seamlessly with the Pax Exam testing framework, providing Karaf-specific options that can be combined with standard Pax Exam options for comprehensive OSGi integration testing.
82

83
## Capabilities
84

85
### Distribution Configuration
86

87
Core functionality for setting up and configuring Karaf distributions for testing, including framework URL specification, version management, and runtime behavior control.
88

89
```java { .api }
90
// Primary entry point for distribution configuration
91
public static KarafDistributionBaseConfigurationOption karafDistributionConfiguration();
92
public static KarafDistributionBaseConfigurationOption karafDistributionConfiguration(
93
    String frameworkURL, String name, String karafVersion);
94
```
95

96
[Distribution Configuration](./distribution-configuration.md)
97

98
### Configuration File Management  
99

100
Comprehensive system for modifying Karaf configuration files during test setup, supporting put, extend, and replace operations on any configuration file.
101

102
```java { .api }
103
// Configuration file modification operations
104
public static Option editConfigurationFilePut(String configurationFilePath, String key, Object value);
105
public static Option editConfigurationFileExtend(String configurationFilePath, String key, Object value);
106
public static Option replaceConfigurationFile(String configurationFilePath, File source);
107
```
108

109
[Configuration Management](./configuration-management.md)
110

111
### Feature Management
112

113
Installation and configuration of Karaf features from repositories, enabling comprehensive testing of feature-based OSGi applications.
114

115
```java { .api }
116
// Feature installation from repositories
117
public static KarafFeaturesOption features(String repositoryUrl, String... features);
118
public static KarafFeaturesOption features(UrlReference repositoryUrl, String... features);
119
```
120

121
[Feature Management](./feature-management.md)
122

123
### Runtime Configuration
124

125
Control over Karaf container runtime behavior including logging, debugging, console access, and system-level configuration.
126

127
```java { .api }
128
// Runtime control options
129
public static Option keepRuntimeFolder();
130
public static Option logLevel(LogLevel logLevel);
131
public static Option debugConfiguration();
132
public static Option doNotModifyLogConfiguration();
133
```
134

135
[Runtime Configuration](./runtime-configuration.md)
136

137
### Security and Console Configuration
138

139
Configuration of Karaf security features and console access, including JMX RBAC security and remote shell configuration.
140

141
```java { .api }
142
// Console and security configuration
143
public static KarafDistributionConfigurationConsoleOption configureConsole();
144
public static KarafDistributionConfigurationSecurityOption configureSecurity();
145
```
146

147
[Security and Console](./security-console.md)
148

149
### Library-Specific Options
150

151
Options for controlling default library behavior and overriding standard deployments.
152

153
```java { .api }
154
// Override default JUnit bundle deployment
155
public static OverrideJUnitBundlesOption overrideJUnitBundles();
156
```
157

158
## Key Types
159

160
```java { .api }
161
// Core option types
162
interface Option {
163
    // Marker interface for all Pax Exam options
164
}
165

166
// Log level enumeration
167
enum LogLevel {
168
    TRACE, DEBUG, INFO, WARN, ERROR
169
}
170

171
// Configuration pointer for type-safe configuration
172
class ConfigurationPointer {
173
    public ConfigurationPointer(String configurationFilePath, String key);
174
    public String getConfigurationFilePath();
175
    public String getKey();
176
}
177

178
// Library-specific option for overriding JUnit bundles
179
class OverrideJUnitBundlesOption implements Option {
180
}
181
```