What it is
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.
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.
Installation
Add dependency in pom.xml:
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-configuration2</artifactId>
<version>2.9.1</version>
</dependency>Getting started
The smallest useful thing you can do with it, and what each part means.
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);import org.apache.commons.configuration2.XMLConfiguration;
XMLConfiguration xmlConfig = configs.xml(new File("config.xml"));
String dbUrl = xmlConfig.getString("database.url");
System.out.println(dbUrl);Advanced usage
Where the library earns its place over a simpler alternative.
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);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);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();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/logsErrors and fixes
The failures you are most likely to hit, and what actually resolves them.
- 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.
Background
Why it exists, and what it was reacting to.
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.