How to Hot‑Reload Spring Boot Config Files with Commons‑Configuration

1. Introduction

When a Spring Boot application needs to change configuration properties at runtime, the properties file should be placed outside the jar and its location provided via the --spring.config.location command‑line argument or environment variables. To reload the file without restarting, a reloading strategy is required.

2. Practical Example

2.1 Add Dependency

<dependency>
  <groupId>commons-configuration</groupId>
  <artifactId>commons-configuration</artifactId>
  <version>1.10</version>
</dependency>

2.2 Define PropertiesConfiguration Bean

@Bean
@ConditionalOnProperty(name = "spring.config.location", matchIfMissing = false)
PropertiesConfiguration propertiesConfiguration(@Value("${spring.config.location}") String path) throws Exception {
    ClassPathResource resource = new ClassPathResource(path);
    PropertiesConfiguration configuration = new PropertiesConfiguration(resource.getFile());
    configuration.setReloadingStrategy(new FileChangedReloadingStrategy());
    return configuration;
}

Configuration can be customized, e.g., setting a refresh delay:

PropertiesConfiguration propertiesConfiguration(@Value("${spring.config.location}") String path,
                                              @Value("${pack.refreshDelay:3000}") Long refreshDelay) {
    ClassPathResource resource = new ClassPathResource(path);
    PropertiesConfiguration configuration = new PropertiesConfiguration(resource.getFile());
    FileChangedReloadingStrategy strategy = new FileChangedReloadingStrategy();
    strategy.setRefreshDelay(refreshDelay);
    configuration.setReloadingStrategy(strategy);
    return configuration;
}

2.3 Reload Environment Properties

To reload properties loaded through Spring’s Environment, extend PropertySource and return values from the PropertiesConfiguration instance.

public class ReloadablePropertySource extends PropertySource<Object> {
    private final PropertiesConfiguration propertiesConfiguration;
    public ReloadablePropertySource(String name, PropertiesConfiguration propertiesConfiguration) {
        super(name);
        this.propertiesConfiguration = propertiesConfiguration;
    }
    @Override
    public Object getProperty(String name) {
        return propertiesConfiguration.getProperty(name);
    }
}

Register this custom source in the environment and access properties via Environment#getProperty.

2.4 Accessing Updated Properties

private final Environment env;
public ReloadConfigController(Environment env) {
    this.env = env;
}
@GetMapping("/get")
public Object get() {
    return this.env.getProperty("pack.title");
}

After changing pack.title in the external file, the next request returns the new value without restarting the service.

2.5 Remarks

Commons‑configuration does not support YAML; use commons‑configuration2 for that. For beans annotated with @ConfigurationProperties or @Value, similar reloading can be achieved, but singleton beans may require additional handling such as destroying and recreating the bean or using Spring Cloud Actuator.