Spring Configuration & Profiles

Externalizing Configuration with Properties

18 min Lesson 4 of 13

Externalizing Configuration with Properties

Hard-coding configuration values — database URLs, API keys, timeouts, feature flags — directly into your Java classes is one of the most common mistakes in early Spring projects. The moment you need to run the same application against a staging database or rotate a secret, you are forced to recompile or redeploy. Spring's externalized configuration system eliminates this problem by keeping those values in .properties files that live outside compiled code, and injecting them into beans at startup.

This lesson covers the two core mechanisms: @PropertySource for explicit file loading, and the Environment API for programmatic access. Lesson 5 builds on top of this with @Value and SpEL for injecting values directly into fields and constructor parameters.

Why Externalize Configuration?

The twelve-factor app methodology mandates a strict separation between code and config. Practically this means:

The same compiled JAR runs in every environment — development, CI, staging, production.
Secrets never appear in version control.
Changing a value (e.g., a connection pool size) requires no recompile and no new build artefact.
Operations teams can tune behaviour without touching source code.

The @PropertySource Annotation

@PropertySource tells Spring to load a .properties file and register its key-value pairs in the application's Environment. You place it on a @Configuration class.

Suppose you have this file at src/main/resources/app.properties:

# app.properties
datasource.url=jdbc:postgresql://localhost:5432/orders
datasource.username=orders_user
datasource.password=changeme
datasource.pool.size=10

mail.host=smtp.example.com
mail.port=587
mail.from=noreply@example.com

Load it into a configuration class:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
import org.springframework.core.env.Environment;

@Configuration
@PropertySource("classpath:app.properties")
public class AppConfig {

    private final Environment env;

    public AppConfig(Environment env) {
        this.env = env;
    }

    @Bean
    public DataSourceProperties dataSourceProperties() {
        DataSourceProperties props = new DataSourceProperties();
        props.setUrl(env.getRequiredProperty("datasource.url"));
        props.setUsername(env.getRequiredProperty("datasource.username"));
        props.setPassword(env.getRequiredProperty("datasource.password"));
        props.setPoolSize(env.getProperty("datasource.pool.size", Integer.class, 5));
        return props;
    }
}

classpath: vs file: vs https: The location string in @PropertySource is a Spring resource path. classpath: resolves from the JVM classpath (your JAR or resources/ folder). file:/etc/myapp/secrets.properties reads from the filesystem at runtime — useful for secrets injected by a container orchestrator. https:// is also supported but rarely used for properties.

Using the Environment API

org.springframework.core.env.Environment is Spring's unified abstraction over all property sources. Once a file is loaded via @PropertySource, its keys are available through this API from anywhere in the application context.

Key methods you need to know:

env.getProperty("key") — returns the value or null if the key does not exist.
env.getProperty("key", "defaultValue") — returns the value or a default string.
env.getProperty("key", Integer.class) — returns the value converted to the requested type, or null.
env.getProperty("key", Integer.class, 10) — typed lookup with a default.
env.getRequiredProperty("key") — throws IllegalStateException if the key is missing; the preferred choice for mandatory values.
env.containsProperty("key") — boolean check, useful for optional feature flags.

Multiple Files and Stacking

You can load several files on a single class using @PropertySources (the container annotation) or the Java 8 repeating-annotation syntax:

@Configuration
@PropertySource("classpath:defaults.properties")
@PropertySource("classpath:overrides.properties")   // Java 8 repeatable
public class MultiSourceConfig {
    // keys from overrides.properties WIN over defaults.properties
    // when the same key appears in both
}

When the same key exists in multiple sources, the last one registered wins. This makes it straightforward to ship sensible defaults and let a team-specific or environment-specific file override only what differs.

Naming convention: Keep the base file (e.g., application.properties) in version control with non-sensitive defaults and placeholder comments. A companion file like application-local.properties (git-ignored) holds developer-specific overrides. In Spring Boot this is built in; in plain Spring you wire it manually with @PropertySource.

Ignoring Missing Files with ignoreResourceNotFound

By default, if the file named in @PropertySource does not exist, Spring throws an exception at context startup. You can relax this for optional files:

@PropertySource(
    value = "classpath:local-overrides.properties",
    ignoreResourceNotFound = true
)

Use this for files that are optional — developer overrides, local secrets, test fixtures — so the application starts cleanly even when the file is absent.

Property Placeholders in the Values Themselves

Spring resolves ${placeholder} syntax inside property values, allowing you to compose values from other properties:

# base.properties
app.env=production
app.name=OrderService
app.full.name=${app.name}-${app.env}   # resolves to: OrderService-production

log.dir=/var/log
log.file=${log.dir}/app.log            # resolves to: /var/log/app.log

This works automatically once you register a PropertySourcesPlaceholderConfigurer bean (in plain Spring) or rely on Spring Boot's auto-configuration, which registers it for you.

Plain Spring requires explicit registration. If you are not using Spring Boot, ${...} placeholders in @Value annotations and XML configuration are only resolved if a PropertySourcesPlaceholderConfigurer bean is present. Declare it as a static bean so it is processed before other beans:

@Bean
public static PropertySourcesPlaceholderConfigurer placeholderConfigurer() {
    return new PropertySourcesPlaceholderConfigurer();
}

In Spring Boot this bean is registered automatically — you never need to add it yourself.

@PropertySource with a Factory: Encoding and Custom Formats

By default Spring reads .properties files as ISO-8859-1. If your values contain UTF-8 characters (Arabic text, accented letters, CJK characters) you must declare the encoding explicitly:

@PropertySource(value = "classpath:i18n-config.properties", encoding = "UTF-8")

For non-standard formats (YAML, TOML, encrypted property files), Spring allows a custom PropertySourceFactory:

import org.springframework.core.env.PropertySource;
import org.springframework.core.io.support.EncodedResource;
import org.springframework.core.io.support.PropertySourceFactory;

import java.io.IOException;
import java.util.Properties;

public class YamlPropertySourceFactory implements PropertySourceFactory {

    @Override
    public PropertySource<?> createPropertySource(String name, EncodedResource resource)
            throws IOException {
        // load the YAML resource and wrap it as a MapPropertySource
        // (implementation uses SnakeYAML or Spring's YamlPropertiesFactoryBean)
        Properties props = loadYaml(resource);
        return new org.springframework.core.env.PropertiesPropertySource(
            resource.getResource().getFilename(), props);
    }

    private Properties loadYaml(EncodedResource resource) throws IOException {
        org.springframework.boot.env.YamlPropertySourceLoader loader =
            new org.springframework.boot.env.YamlPropertySourceLoader();
        // simplified — production code would iterate the loaded sources
        Properties result = new Properties();
        return result;
    }
}

Then reference it on the annotation:

@PropertySource(
    value = "classpath:config.yml",
    factory = YamlPropertySourceFactory.class
)

Spring Boot does this for you. If you are on Spring Boot, application.yml is loaded automatically by YamlPropertySourceLoader — no custom factory needed. The custom factory pattern is primarily useful in plain Spring or when loading additional non-standard files alongside the main configuration.

Property Source Priority

Spring maintains a prioritised list of property sources. In Spring Boot the order (highest priority first) is roughly:

Command-line arguments (--server.port=9090)
OS environment variables (SPRING_DATASOURCE_URL)
JVM system properties (-Dspring.profiles.active=prod)
Profile-specific properties (application-prod.properties)
Default properties (application.properties)
Files added via @PropertySource

Files you load with @PropertySource sit at the bottom of this stack. This is intentional: it means system environment variables and command-line arguments always override what is in your committed properties files, giving operators full control at runtime without touching source code.

Summary

@PropertySource is the explicit, annotation-driven way to load a .properties file into Spring's Environment. Once loaded, keys are accessible through Environment.getProperty() or getRequiredProperty(). You can stack multiple files, ignore missing optional files, compose values with ${} placeholders, and even plug in custom factories for non-standard formats. In the next lesson you will see how to skip the Environment API calls entirely and inject values straight into bean fields and constructor parameters using @Value.