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

Integration testing framework for OSGi applications running in Apache Karaf containers

—

Pending

Overview

Eval results

Files

Configuration Management

Name: tessl/maven-org-ops4j-pax-exam--pax-exam-container-karaf
Author: tessl

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.

Capabilities

Configuration File Put Operations

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

/**
 * Put/replace a configuration value using file path and key
 * @param configurationFilePath Path to configuration file relative to karaf.home
 * @param key Configuration property key
 * @param value Configuration property value
 * @return Configuration option
 */
public static Option editConfigurationFilePut(String configurationFilePath, String key, Object value);

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

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

Usage Examples:

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

// Put using string paths
Option jmxPort = editConfigurationFilePut(
    "etc/org.apache.karaf.management.cfg", 
    "rmiRegistryPort", 
    "1099"
);

// Put using type-safe pointers
Option jmxPortSafe = editConfigurationFilePut(
    ManagementCfg.RMI_REGISTRY_PORT, 
    "1099"
);

// Put from properties file
File configSource = new File("test-config.properties");
Option[] multipleConfigs = editConfigurationFilePut(
    "etc/system.properties",
    configSource,
    "karaf.name", "org.osgi.framework.bootdelegation"
);

Configuration File Extend Operations

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

/**
 * Extend a configuration value using file path and key
 * @param configurationFilePath Path to configuration file relative to karaf.home
 * @param key Configuration property key
 * @param value Value to append to existing configuration
 * @return Configuration option
 */
public static Option editConfigurationFileExtend(String configurationFilePath, String key, Object value);

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

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

Usage Examples:

import org.ops4j.pax.exam.karaf.options.configs.CustomProperties;

// Extend system packages
Option extendSystemPackages = editConfigurationFileExtend(
    "etc/config.properties",
    "org.osgi.framework.system.packages.extra",
    "com.example.api,com.example.util"
);

// Extend using type-safe pointer
Option extendSystemPackagesSafe = editConfigurationFileExtend(
    CustomProperties.SYSTEM_PACKAGES_EXTRA,
    "com.example.api,com.example.util"
);

// Extend boot delegation
Option extendBootDelegation = editConfigurationFileExtend(
    CustomProperties.BOOTDELEGATION,
    "sun.*,com.sun.*"
);

Configuration File Replacement

Replace entire configuration files with custom versions during test setup.

/**
 * Replace an entire configuration file with a custom version
 * @param configurationFilePath Path to configuration file to replace
 * @param source File containing replacement content
 * @return Configuration option
 */
public static Option replaceConfigurationFile(String configurationFilePath, File source);

Usage Examples:

// Replace logging configuration
File customLoggingConfig = new File("src/test/resources/custom-logging.cfg");
Option replaceLogging = replaceConfigurationFile(
    "etc/org.ops4j.pax.logging.cfg",
    customLoggingConfig
);

// Replace system properties
File customSystemProps = new File("src/test/resources/system.properties");
Option replaceSystemProps = replaceConfigurationFile(
    "etc/system.properties",
    customSystemProps
);

Configuration File Options

Implementation classes for configuration file modifications.

/**
 * Abstract base class for configuration file modifications
 */
abstract class KarafDistributionConfigurationFileOption implements Option {
    
    public KarafDistributionConfigurationFileOption(ConfigurationPointer pointer, Object value);
    public KarafDistributionConfigurationFileOption(String configurationFilePath, String key, Object value);
    public KarafDistributionConfigurationFileOption(String configurationFilePath);
    
    public String getConfigurationFilePath();
    public String getKey();
    public Object getValue();
}

/**
 * Put/replace configuration file operation
 */
class KarafDistributionConfigurationFilePutOption extends KarafDistributionConfigurationFileOption {
    
    public KarafDistributionConfigurationFilePutOption(String configurationFilePath, String key, Object value);
    public KarafDistributionConfigurationFilePutOption(ConfigurationPointer pointer, Object value);
}

/**
 * Extend configuration file operation  
 */
class KarafDistributionConfigurationFileExtendOption extends KarafDistributionConfigurationFileOption {
    
    public KarafDistributionConfigurationFileExtendOption(String configurationFilePath, String key, Object value);
    public KarafDistributionConfigurationFileExtendOption(ConfigurationPointer pointer, Object value);
}

/**
 * Replace configuration file operation
 */
class KarafDistributionConfigurationFileReplacementOption extends KarafDistributionConfigurationFileOption {
    
    public KarafDistributionConfigurationFileReplacementOption(String configurationFilePath, File source);
    public File getSource();
}

Type-Safe Configuration Pointers

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

/**
 * Type-safe reference to configuration file and key
 */
class ConfigurationPointer {
    
    public ConfigurationPointer(String configurationFilePath, String key);
    public String getConfigurationFilePath();
    public String getKey();
}

Available Configuration Pointers

CustomProperties - etc/config.properties:

class CustomProperties {
    public static final String FILE_PATH = "etc/config.properties";
    public static final ConfigurationPointer KARAF_FRAMEWORK; // Framework type (felix/equinox)
    public static final ConfigurationPointer SYSTEM_PACKAGES_EXTRA; // System packages extra
    public static final ConfigurationPointer BOOTDELEGATION; // Boot delegation packages
}

FeaturesCfg - etc/org.apache.karaf.features.cfg:

class FeaturesCfg {
    public static final String FILE_PATH = "etc/org.apache.karaf.features.cfg";
    public static final ConfigurationPointer REPOSITORIES; // Features repositories list
    public static final ConfigurationPointer BOOT; // Features to install at boot
}

LoggingCfg - etc/org.ops4j.pax.logging.cfg:

class LoggingCfg {
    public static final String FILE_PATH = "etc/org.ops4j.pax.logging.cfg";
    public static final ConfigurationPointer ROOT_LOGGER; // Root logger configuration
}

ManagementCfg - etc/org.apache.karaf.management.cfg:

class ManagementCfg {
    public static final String FILE_PATH = "etc/org.apache.karaf.management.cfg";
    public static final ConfigurationPointer RMI_REGISTRY_PORT; // RMI registry port
    public static final ConfigurationPointer RMI_SERVER_PORT; // RMI server port
}

SystemProperties - etc/system.properties:

class SystemProperties {
    public static final String FILE_PATH = "etc/system.properties";
    public static final ConfigurationPointer KARAF_NAME; // Karaf instance name
}

UsersProperties - etc/users.properties:

class UsersProperties {
    public static final String FILE_PATH = "etc/users.properties";
    public static final ConfigurationPointer KARAF_USER; // Default karaf user
}

WebCfg - etc/org.ops4j.pax.web.cfg:

class WebCfg {
    public static final String FILE_PATH = "etc/org.ops4j.pax.web.cfg";
    public static final ConfigurationPointer HTTP_PORT; // HTTP service port
}

JreProperties - etc/jre.properties:

class JreProperties {
    public static final String FILE_PATH = "etc/jre.properties";
}

Usage Patterns

Combining Operations

@Configuration
public Option[] config() {
    return new Option[] {
        karafDistributionConfiguration(),
        
        // Set JMX ports
        editConfigurationFilePut(ManagementCfg.RMI_REGISTRY_PORT, "1099"),
        editConfigurationFilePut(ManagementCfg.RMI_SERVER_PORT, "44444"),
        
        // Extend system packages
        editConfigurationFileExtend(
            CustomProperties.SYSTEM_PACKAGES_EXTRA,
            "com.example.api,com.example.util"
        ),
        
        // Replace logging configuration
        replaceConfigurationFile(
            "etc/org.ops4j.pax.logging.cfg",
            new File("src/test/resources/test-logging.cfg")
        )
    };
}

Properties File Loading

// Load multiple configurations from properties file
File testConfig = new File("src/test/resources/test.properties");
Option[] systemConfigs = editConfigurationFilePut(
    "etc/system.properties",
    testConfig,
    "karaf.name", "karaf.base", "java.protocol.handler.pkgs"
);

Error Handling

Configuration file operations throw IllegalStateException for:

Invalid configuration file paths
Inaccessible source files for replacement
Properties file parsing errors
Missing configuration directories during test execution

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

index.md

runtime-configuration.md

security-console.md

tile.json

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