Apache Commons Configuration

Language: Java

Utilities/Configuration

Commons Configuration was created to simplify managing configuration data in Java applications. It abstracts the details of different configuration formats, allowing developers to read, write, and monitor configurations consistently. Features like hierarchical structures, interpolated variables, and reloading strategies make it ideal for enterprise and complex applications where configuration management is critical.

Apache Commons Configuration provides a unified API for accessing configuration data from various sources, including properties files, XML, INI, JSON, and databases. It supports hierarchical configurations, automatic reloading, and combined configuration sources.

Installation

maven:

Add dependency in pom.xml:
<dependency>
  <groupId>org.apache.commons</groupId>
  <artifactId>commons-configuration2</artifactId>
  <version>2.9.1</version>
</dependency>

gradle:

Add dependency in build.gradle:
implementation 'org.apache.commons:commons-configuration2:2.9.1'

Usage

Commons Configuration allows reading and writing configurations from multiple sources, combining different sources, handling hierarchical data, and monitoring changes. It supports properties, XML, JSON, INI, database-backed configurations, and more.

Loading a properties file

import org.apache.commons.configuration2.PropertiesConfiguration;
import org.apache.commons.configuration2.builder.fluent.Configurations;

Configurations configs = new Configurations();
PropertiesConfiguration config = configs.properties(new File("config.properties"));
String value = config.getString("app.name");
System.out.println(value);

Loads a properties file and reads a configuration value.

Reading an XML configuration

import org.apache.commons.configuration2.XMLConfiguration;
XMLConfiguration xmlConfig = configs.xml(new File("config.xml"));
String dbUrl = xmlConfig.getString("database.url");
System.out.println(dbUrl);

Reads a value from an XML configuration file.

Hierarchical configuration

import org.apache.commons.configuration2.HierarchicalConfiguration;
import org.apache.commons.configuration2.tree.ImmutableNode;

HierarchicalConfiguration<ImmutableNode> subConfig = xmlConfig.configurationAt("database");
String user = subConfig.getString("username");
System.out.println(user);

Accesses a subsection of a hierarchical configuration.

Combining multiple configuration sources

import org.apache.commons.configuration2.CompositeConfiguration;
CompositeConfiguration composite = new CompositeConfiguration();
composite.addConfiguration(propertiesConfig);
composite.addConfiguration(xmlConfig);
String value = composite.getString("app.name");
System.out.println(value);

Combines multiple configuration sources into one unified view.

Automatic reloading

import org.apache.commons.configuration2.builder.ReloadingFileBasedConfigurationBuilder;
import org.apache.commons.configuration2.builder.fluent.Parameters;
import org.apache.commons.configuration2.reloading.PeriodicReloadingTrigger;

ReloadingFileBasedConfigurationBuilder<PropertiesConfiguration> builder =
    new ReloadingFileBasedConfigurationBuilder<>(PropertiesConfiguration.class)
    .configure(new Parameters().fileBased().setFile(new File("config.properties")));
// Trigger reload every 5 seconds
PeriodicReloadingTrigger trigger = new PeriodicReloadingTrigger(builder.getReloadingController(), null, 5, TimeUnit.SECONDS);
trigger.start();

Sets up automatic reloading of a properties file every 5 seconds.

Interpolated values

config.addProperty("app.home", "/usr/local/app");
config.addProperty("app.log", "${app.home}/logs");
System.out.println(config.getString("app.log")); // Outputs /usr/local/app/logs

Supports variable interpolation within configuration values.

Error Handling

ConfigurationException: Occurs when a configuration file cannot be read or parsed. Check file paths, syntax, and permissions.

NoSuchElementException: Occurs when attempting to access a missing configuration key. Use getString with a default value or validate keys.

Best Practices

Use CompositeConfiguration to merge multiple configuration sources cleanly.

Use hierarchical configurations for structured data like XML or JSON.

Leverage automatic reloading to update configuration without restarting the application.

Validate configuration values during startup to catch errors early.

Keep sensitive configuration (like passwords) in secure sources or environment variables.

Official Docs Github