Blog Docs Log in Get started

tessl/maven-org-ops4j-pax-exam--pax-exam-container-karaf

Integration testing framework for OSGi applications running in Apache Karaf containers

—

Pending

Distribution Configuration

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.

Capabilities

Basic Distribution Configuration

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

/**
 * Creates a default Karaf distribution configuration
 * @return Distribution configuration option with defaults
 */
public static KarafDistributionBaseConfigurationOption karafDistributionConfiguration();

/**
 * Creates a Karaf distribution configuration with specific parameters
 * @param frameworkURL URL to the Karaf distribution archive
 * @param name Framework name for identification
 * @param karafVersion Karaf version string
 * @return Configured distribution option
 */
public static KarafDistributionBaseConfigurationOption karafDistributionConfiguration(
    String frameworkURL, String name, String karafVersion);

Usage Examples:

import static org.ops4j.pax.exam.karaf.options.KarafDistributionOption.*;

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

// Specific Karaf version and location
Option customConfig = karafDistributionConfiguration(
    "mvn:org.apache.karaf/apache-karaf/4.2.0/zip",
    "Apache Karaf",
    "4.2.0"
);

// Using existing Karaf installation
Option existingConfig = karafDistributionConfiguration()
    .existing(new File("/opt/karaf"));

Distribution Configuration Builder

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

/**
 * Base configuration class for Karaf distributions
 */
class KarafDistributionBaseConfigurationOption implements Option {
    
    // Constructors
    public KarafDistributionBaseConfigurationOption();
    public KarafDistributionBaseConfigurationOption(String frameworkURL, String name, String karafVersion);
    public KarafDistributionBaseConfigurationOption(File existing);
    public KarafDistributionBaseConfigurationOption(MavenUrlReference frameworkURLReference, String name, String karafVersion);
    public KarafDistributionBaseConfigurationOption(MavenUrlReference frameworkURLReference);
    public KarafDistributionBaseConfigurationOption(KarafDistributionBaseConfigurationOption base);
    
    // Fluent configuration methods (all return this)
    public KarafDistributionBaseConfigurationOption frameworkUrl(String frameworkURL);
    public KarafDistributionBaseConfigurationOption frameworkUrl(MavenUrlReference frameworkURL);
    public KarafDistributionBaseConfigurationOption existing(File existing);
    public KarafDistributionBaseConfigurationOption name(String name);
    public KarafDistributionBaseConfigurationOption karafVersion(String karafVersion);
    public KarafDistributionBaseConfigurationOption karafMain(String karafMain);
    public KarafDistributionBaseConfigurationOption karafData(String karafData);
    public KarafDistributionBaseConfigurationOption karafEtc(String karafEtc);
    public KarafDistributionBaseConfigurationOption karafLog(String karafLog);
    public KarafDistributionBaseConfigurationOption unpackDirectory(File unpackDirectory);
    public KarafDistributionBaseConfigurationOption directoryNameFormat(String directoryNameFormat);
    public KarafDistributionBaseConfigurationOption useDeployFolder(boolean useDeployFolder);
    public KarafDistributionBaseConfigurationOption runEmbedded(boolean runEmbedded);
    
    // Getter methods
    public String getFrameworkURL();
    public File getExisting();
    public String getName();
    public String getKarafVersion();
    public String getKarafMain();
    public String getKarafData();
    public String getKarafEtc();
    public String getKarafLog();
    public File getUnpackDirectory();
    public String getDirectoryNameFormat();
    public boolean isUseDeployFolder();
    public boolean isRunEmbedded();
}

Usage Examples:

// Complete fluent configuration
Option fluentConfig = karafDistributionConfiguration()
    .frameworkUrl("mvn:org.apache.karaf/apache-karaf/4.2.0/zip")
    .karafVersion("4.2.0")
    .name("Test Karaf")
    .karafData("data")
    .karafEtc("etc")
    .karafLog("log")
    .useDeployFolder(true)
    .runEmbedded(false)
    .unpackDirectory(new File("target/pax"));

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

// Custom main class and directories
Option customConfig = karafDistributionConfiguration()
    .karafMain("com.example.CustomMain")
    .karafData("custom-data")
    .directoryNameFormat("test-%s");

Standard Distribution Configuration

Standard implementation of the base distribution configuration.

/**
 * Standard Karaf distribution configuration implementation
 */
class KarafDistributionConfigurationOption extends KarafDistributionBaseConfigurationOption {
    
    public KarafDistributionConfigurationOption();
    public KarafDistributionConfigurationOption(KarafDistributionBaseConfigurationOption base);
    public KarafDistributionConfigurationOption(MavenUrlReference frameworkURLReference, String name, String karafVersion);
    public KarafDistributionConfigurationOption(String frameworkURL, String name, String karafVersion);
}

Kit-Based Distribution Configuration

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

/**
 * Kit-based distribution configuration with platform-specific script handling
 */
class KarafDistributionKitConfigurationOption extends KarafDistributionBaseConfigurationOption {
    
    // Platform enumeration
    enum Platform {
        WINDOWS, NIX
    }
    
    // Constructors
    public KarafDistributionKitConfigurationOption(KarafDistributionBaseConfigurationOption base, Platform platform);
    public KarafDistributionKitConfigurationOption(MavenUrlReference frameworkURLReference, String name, String karafVersion, Platform platform);
    public KarafDistributionKitConfigurationOption(MavenUrlReference frameworkURLReference, Platform platform);
    public KarafDistributionKitConfigurationOption(String frameworkURL, String name, String karafVersion, Platform platform);
    
    // Platform-specific methods
    public KarafDistributionKitConfigurationOption filesToMakeExecutable(String... platformRelativeFilePath);
    public KarafDistributionKitConfigurationOption executable(String platformRelativeFilePath);
    public Platform getPlatform();
    public List<String> getMakeExec();
    public String getExec();
}

Usage Examples:

// Windows kit configuration
Option windowsKit = new KarafDistributionKitConfigurationOption(
    "mvn:org.apache.karaf/apache-karaf/4.2.0/zip",
    "Apache Karaf", 
    "4.2.0",
    KarafDistributionKitConfigurationOption.Platform.WINDOWS
)
.executable("bin/karaf.bat")
.filesToMakeExecutable("bin/start.bat", "bin/stop.bat");

// Unix/Linux kit configuration  
Option nixKit = new KarafDistributionKitConfigurationOption(
    "mvn:org.apache.karaf/apache-karaf/4.2.0/zip",
    "Apache Karaf",
    "4.2.0", 
    KarafDistributionKitConfigurationOption.Platform.NIX
)
.executable("bin/karaf")
.filesToMakeExecutable("bin/start", "bin/stop");

Configuration Parameters

Framework URL Options

String URL: Direct URL to Karaf distribution (file://, http://, mvn:// protocols)
MavenUrlReference: Type-safe Maven coordinate reference
File path: Path to existing Karaf installation

Directory Structure Control

karafData: Data directory name (default: "data")
karafEtc: Configuration directory name (default: "etc")
karafLog: Log directory name (default: "log")
unpackDirectory: Where to unpack distributions
directoryNameFormat: Template for runtime directory names

Runtime Behavior

useDeployFolder: Enable hot deployment folder (default: true)
runEmbedded: Run Karaf in embedded mode vs separate process
karafMain: Main class for Karaf startup (default: "org.apache.karaf.main.Main")

Platform Support

Platform.WINDOWS: Windows-specific script handling (.bat files)
Platform.NIX: Unix/Linux script handling (shell scripts)
Executable management: Control over which scripts are executable

Error Handling

Configuration methods throw IllegalStateException for:

Invalid framework URLs
Inaccessible existing installations
Missing required Maven artifacts
Invalid directory paths
Platform-specific script issues

Install with Tessl CLI

npx tessl i tessl/maven-org-ops4j-pax-exam--pax-exam-container-karaf

docs

configuration-management.md

distribution-configuration.md

feature-management.md

runtime-configuration.md

security-console.md