0
# Distribution Configuration
1

2
Core functionality for setting up and configuring Karaf distributions for testing. This capability provides comprehensive control over Karaf distribution selection, installation paths, runtime behavior, and platform-specific configurations.
3

4
## Capabilities
5

6
### Basic Distribution Configuration
7

8
Creates a Karaf distribution configuration option with default settings or specific framework details.
9

10
```java { .api }
11
/**
12
 * Creates a default Karaf distribution configuration
13
 * @return Distribution configuration option with defaults
14
 */
15
public static KarafDistributionBaseConfigurationOption karafDistributionConfiguration();
16

17
/**
18
 * Creates a Karaf distribution configuration with specific parameters
19
 * @param frameworkURL URL to the Karaf distribution archive
20
 * @param name Framework name for identification
21
 * @param karafVersion Karaf version string
22
 * @return Configured distribution option
23
 */
24
public static KarafDistributionBaseConfigurationOption karafDistributionConfiguration(
25
    String frameworkURL, String name, String karafVersion);
26
```
27

28
**Usage Examples:**
29

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

33
// Default configuration (uses Maven Central Karaf)
34
Option defaultConfig = karafDistributionConfiguration();
35

36
// Specific Karaf version and location
37
Option customConfig = karafDistributionConfiguration(
38
    "mvn:org.apache.karaf/apache-karaf/4.2.0/zip",
39
    "Apache Karaf",
40
    "4.2.0"
41
);
42

43
// Using existing Karaf installation
44
Option existingConfig = karafDistributionConfiguration()
45
    .existing(new File("/opt/karaf"));
46
```
47

48
### Distribution Configuration Builder
49

50
Fluent configuration interface for detailed Karaf distribution setup with method chaining.
51

52
```java { .api }
53
/**
54
 * Base configuration class for Karaf distributions
55
 */
56
class KarafDistributionBaseConfigurationOption implements Option {
57
    
58
    // Constructors
59
    public KarafDistributionBaseConfigurationOption();
60
    public KarafDistributionBaseConfigurationOption(String frameworkURL, String name, String karafVersion);
61
    public KarafDistributionBaseConfigurationOption(File existing);
62
    public KarafDistributionBaseConfigurationOption(MavenUrlReference frameworkURLReference, String name, String karafVersion);
63
    public KarafDistributionBaseConfigurationOption(MavenUrlReference frameworkURLReference);
64
    public KarafDistributionBaseConfigurationOption(KarafDistributionBaseConfigurationOption base);
65
    
66
    // Fluent configuration methods (all return this)
67
    public KarafDistributionBaseConfigurationOption frameworkUrl(String frameworkURL);
68
    public KarafDistributionBaseConfigurationOption frameworkUrl(MavenUrlReference frameworkURL);
69
    public KarafDistributionBaseConfigurationOption existing(File existing);
70
    public KarafDistributionBaseConfigurationOption name(String name);
71
    public KarafDistributionBaseConfigurationOption karafVersion(String karafVersion);
72
    public KarafDistributionBaseConfigurationOption karafMain(String karafMain);
73
    public KarafDistributionBaseConfigurationOption karafData(String karafData);
74
    public KarafDistributionBaseConfigurationOption karafEtc(String karafEtc);
75
    public KarafDistributionBaseConfigurationOption karafLog(String karafLog);
76
    public KarafDistributionBaseConfigurationOption unpackDirectory(File unpackDirectory);
77
    public KarafDistributionBaseConfigurationOption directoryNameFormat(String directoryNameFormat);
78
    public KarafDistributionBaseConfigurationOption useDeployFolder(boolean useDeployFolder);
79
    public KarafDistributionBaseConfigurationOption runEmbedded(boolean runEmbedded);
80
    
81
    // Getter methods
82
    public String getFrameworkURL();
83
    public File getExisting();
84
    public String getName();
85
    public String getKarafVersion();
86
    public String getKarafMain();
87
    public String getKarafData();
88
    public String getKarafEtc();
89
    public String getKarafLog();
90
    public File getUnpackDirectory();
91
    public String getDirectoryNameFormat();
92
    public boolean isUseDeployFolder();
93
    public boolean isRunEmbedded();
94
}
95
```
96

97
**Usage Examples:**
98

99
```java
100
// Complete fluent configuration
101
Option fluentConfig = karafDistributionConfiguration()
102
    .frameworkUrl("mvn:org.apache.karaf/apache-karaf/4.2.0/zip")
103
    .karafVersion("4.2.0")
104
    .name("Test Karaf")
105
    .karafData("data")
106
    .karafEtc("etc")
107
    .karafLog("log")
108
    .useDeployFolder(true)
109
    .runEmbedded(false)
110
    .unpackDirectory(new File("target/pax"));
111

112
// Using existing Karaf installation
113
Option existingConfig = karafDistributionConfiguration()
114
    .existing(new File("/opt/karaf"))
115
    .runEmbedded(true);
116

117
// Custom main class and directories
118
Option customConfig = karafDistributionConfiguration()
119
    .karafMain("com.example.CustomMain")
120
    .karafData("custom-data")
121
    .directoryNameFormat("test-%s");
122
```
123

124
### Standard Distribution Configuration
125

126
Standard implementation of the base distribution configuration.
127

128
```java { .api }
129
/**
130
 * Standard Karaf distribution configuration implementation
131
 */
132
class KarafDistributionConfigurationOption extends KarafDistributionBaseConfigurationOption {
133
    
134
    public KarafDistributionConfigurationOption();
135
    public KarafDistributionConfigurationOption(KarafDistributionBaseConfigurationOption base);
136
    public KarafDistributionConfigurationOption(MavenUrlReference frameworkURLReference, String name, String karafVersion);
137
    public KarafDistributionConfigurationOption(String frameworkURL, String name, String karafVersion);
138
}
139
```
140

141
### Kit-Based Distribution Configuration
142

143
Platform-specific distribution configuration for Karaf kit deployments with executable script management.
144

145
```java { .api }
146
/**
147
 * Kit-based distribution configuration with platform-specific script handling
148
 */
149
class KarafDistributionKitConfigurationOption extends KarafDistributionBaseConfigurationOption {
150
    
151
    // Platform enumeration
152
    enum Platform {
153
        WINDOWS, NIX
154
    }
155
    
156
    // Constructors
157
    public KarafDistributionKitConfigurationOption(KarafDistributionBaseConfigurationOption base, Platform platform);
158
    public KarafDistributionKitConfigurationOption(MavenUrlReference frameworkURLReference, String name, String karafVersion, Platform platform);
159
    public KarafDistributionKitConfigurationOption(MavenUrlReference frameworkURLReference, Platform platform);
160
    public KarafDistributionKitConfigurationOption(String frameworkURL, String name, String karafVersion, Platform platform);
161
    
162
    // Platform-specific methods
163
    public KarafDistributionKitConfigurationOption filesToMakeExecutable(String... platformRelativeFilePath);
164
    public KarafDistributionKitConfigurationOption executable(String platformRelativeFilePath);
165
    public Platform getPlatform();
166
    public List<String> getMakeExec();
167
    public String getExec();
168
}
169
```
170

171
**Usage Examples:**
172

173
```java
174
// Windows kit configuration
175
Option windowsKit = new KarafDistributionKitConfigurationOption(
176
    "mvn:org.apache.karaf/apache-karaf/4.2.0/zip",
177
    "Apache Karaf", 
178
    "4.2.0",
179
    KarafDistributionKitConfigurationOption.Platform.WINDOWS
180
)
181
.executable("bin/karaf.bat")
182
.filesToMakeExecutable("bin/start.bat", "bin/stop.bat");
183

184
// Unix/Linux kit configuration  
185
Option nixKit = new KarafDistributionKitConfigurationOption(
186
    "mvn:org.apache.karaf/apache-karaf/4.2.0/zip",
187
    "Apache Karaf",
188
    "4.2.0", 
189
    KarafDistributionKitConfigurationOption.Platform.NIX
190
)
191
.executable("bin/karaf")
192
.filesToMakeExecutable("bin/start", "bin/stop");
193
```
194

195
## Configuration Parameters
196

197
### Framework URL Options
198
- **String URL**: Direct URL to Karaf distribution (file://, http://, mvn:// protocols)
199
- **MavenUrlReference**: Type-safe Maven coordinate reference
200
- **File path**: Path to existing Karaf installation
201

202
### Directory Structure Control
203
- **karafData**: Data directory name (default: "data")
204
- **karafEtc**: Configuration directory name (default: "etc") 
205
- **karafLog**: Log directory name (default: "log")
206
- **unpackDirectory**: Where to unpack distributions
207
- **directoryNameFormat**: Template for runtime directory names
208

209
### Runtime Behavior
210
- **useDeployFolder**: Enable hot deployment folder (default: true)
211
- **runEmbedded**: Run Karaf in embedded mode vs separate process
212
- **karafMain**: Main class for Karaf startup (default: "org.apache.karaf.main.Main")
213

214
### Platform Support
215
- **Platform.WINDOWS**: Windows-specific script handling (.bat files)
216
- **Platform.NIX**: Unix/Linux script handling (shell scripts)
217
- **Executable management**: Control over which scripts are executable
218

219
## Error Handling
220

221
Configuration methods throw `IllegalStateException` for:
222
- Invalid framework URLs
223
- Inaccessible existing installations
224
- Missing required Maven artifacts
225
- Invalid directory paths
226
- Platform-specific script issues