Spring Property Injection Concepts
Internal
Overview
Spring has two different, but related kinds of configuration: bean wiring, which refers to declaring application components and their dependencies, and how those dependencies should be injected into each other, as described in the Dependency Injection and Inversion of Control Container section, and property injection, which is the process that allows external pieces of data, known as configuration properties, to be provided to the application runtime at startup or while it is running, in form of Java system properties, environment variables and by other means. This section addresses property injection concepts. These two concepts intermingle when we talk about profiles, as both bean wiring and property injection are subject to profiles.
The Environment Abstraction
The environment is an abstraction integrated in the container that models two key aspects of the application environment: configuration properties and profiles.
The environment implements Environment and can be obtained directly from the application context, as follows:
import org.springframework.core.env.Environment;
ApplicationContext applicationContext = ...
Environment environment = applicationContext.getEnvironment();
The environment can be injected into a component and accessed programmatically as follows:
@Autowired
private Environment environment;
Configuration Properties
Configuration properties are pieces of data coded into Spring components using the JavaBeans property conventions. They usually have a corresponding member variable, a getter and a setter. The Spring Framework provides conventions and mechanisms to automatically inject values into configuration properties, while those values come from several different property sources.
The Spring environment provides the user with a convenient service interface for configuring property sources and resolving properties from them.
The Spring environment is the only source of configuration properties for components needing them. The environment abstracts the origins of properties and applies precedence rules when the same property is specified in more than one source. It pulls property values from several sources: Java system properties, command-line arguments, environment variables, configuration files, etc. The property sources are described in detail in their corresponding sections, below.
Reading Properties from Environment
The availability of a property in one of the environment's property sources can be checked with:
if (environment.containsProperty(propertyName)) {
...
}
If the property is available, it can be obtained with:
environment.getProperty(propertyName);
Spring Boot offers a facility to inject property values into components coded using JavaBeans conventions:
The PropertySource Abstraction
The Spring environment abstraction integrates and searches over a configurable hierarchy of property sources, consolidated under a PropertySources interface, each implementing PropertySource. The mechanism is configurable, custom property sources can be integrated.
Property Sources
Java System Properties
Java system properties are exposed to the environment via a PropertySource wrapped around System.getProperties(). Properties declared with -D on java command line are available via the environment abstraction.
Java System Properties Name Translation Syntax and Rules
A "secretApiKey" variable in the "novaordis.playground" name space can be set as:
-Dnovaordis.playground.secretApiKey=...
Environment Variables
Environment variables are exposed to the environment via a PropertySource wrapped around System.getenv().
The naming style should accommodate restrictions placed on environment variable names by the operating system.
export SERVER_PORT=9999
The environment variables present in the Spring application environment are automatically converted to system property, using specific name translation rules, and they're available in the environment.
Environment Variable Name Translation Syntax and Rules
MY_TEST_ENVIRONMENT_VARIABLE -> my.test.environment.variable
A "secretApiKey" variable in the "novaordis.playground" name space can be set as:
NOVAORDIS_PLAYGROUND_SECRET_API_KEY.
Spring Boot Command-Line Arguments
This option to specify system property is only available to Spring Boot applications.
Do test.
java -jar ... --<property.name>=<value>
Example:
java -jar ... --server.port=9999
Property Configuration Files
application.properties
application.yml
bootstrap.yml
Map Objects
JNDI
Servlet Configuration
Servlet configuration is accessible through a StandardServletEnvironment.
Servlet Context Parameters
Servlet context parameters are accessible through a StandardServletEnvironment.
Configuration Service (Spring Cloud Config Server)
The configuration service is also referred to as config (configuration) server. For more details, see:
Custom Property Source
API
ConfigurableApplicationContext ctx = ...
MutablePropertySources sources = ctx.getEnvironment().getPropertySources();
sources.addFirst(new MyPropertySource());
@PropertySource
TODO Spring Framework Core Technologies Section 1.13.3 Using @PropertySource
Precedence
Property values are not merged but rather completely overridden by a preceding entry. The property sources are scanned in the descending order of their priority, and when a hit is encountered, the scan ends, and the found value is returned. For a StandardEnvironment, the full hierarchy is as follows, with the highest-precedence entries at the top:
- JVM system properties (-D command-line arguments).
- OS environment variables.
- application.properties
For a StandardServletEnvironment, the full hierarchy is as follows, with the highest-precedence entries at the top:
- ServletConfig parameters.
- ServletContext parameters (web.xml context-param entries).
- JNDI environment variables (java:comp/env/ entries).
- JVM system properties (-D command-line arguments).
- OS environment variables.
Property Placeholders
Property placeholders can be used in XML configuration elements (but not in other property values - that only works in Spring Boot). Historically, the value of placeholders in elements could be resolved only against JVM system properties or environment variables, but with the recent versions of the Spring Framework, that is no longer the case, because the environment abstraction is integrated throughout the container. More details here: Spring Framework Core Technologies Section 1.13.4 Placeholder Resolution in Statements.
Also see:
Profiles
A profile is a named, logical group of bean definitions and configuration properties to be registered with the container only if the given profile is active. Beans may be assigned to a profile whether they are defined in XML or with annotations. The environment determines which profiles - if any - are currently active, and which profiles - if any - should be active by default. Profiles are a solution for the problem posed by the fact that configuration details differ when applications are deployed in different runtime environments. The classical example is the database URL and credentials: the testing environment uses a different database than the production environment. One way to address the problem is to configure these details with environment variables. Another option is to use profiles.
Default Profile
A default profile represents the profile (or profiles) that are enabled by default. The default profile's name is "default". Components can be declared to be registered by default, probably redundantly with:
@Profile("default")
...
If no profile is active, all components belonging to the default profile are created and registered. The default profile is a way to provide a default definition for one or more beans. If any profile is enabled, the default profile does not apply. The name of the default profile can be changed by using setDefaultProfiles() on the Environment or declaratively by using the "spring.profiles.default" property.
Relationship between default and active profiles.
Active Profile
More than one profile can be active at a time.
A profile, or more than one profiles can be activated declaratively using the spring.profiles.active system property. When more than one profile is active, the names of the active profiles should be separated by comma:
java -Dspring.profiles.active="red[,blue,...]" ...
the SPRING_PROFILES_ACTIVE environment variable (note that SPRING_ACTIVE_PROFILES has no effect). This is the preferred method to communicate to a containerized Spring Boot application which profile(s) is active:
export SPRING_PROFILES_ACTIVE="red[,blue,...]"
servlet context parameters in web.xml, JNDI entries, etc.
Spring Boot allows for a special command-line syntax to specify the active profile.
Active profiles can be determined programmatically from the Environment interface at runtime:
@Autowire
Environment environment;
...
environment.getActiveProfiles()
Active profiles can also be activated programmatically via the API exposed by the Environment interface:
For the programmatic configuration to work, setActiveProfile() needs to be called before the components are registered with register(), as shown in the example below.
AnnotationConfigApplicationContext applicationContext = new AnnotationConfigApplicationContext();
applicationContext.getEnvironment().setActiveProfiles("blue");
applicationContext.scan("playground.spring.profile");
applicationContext.refresh();
Active Profile Example
Active Profiles in Integration Tests
In integration tests, the association between a test and active profile (profiles) can be declared with the @ActiveProfiles annotation:
Profile Expressions
The profile string may contain a simple profile name or a profile expression. A profile expression allows for more complicated profile logic to be expressed, and supports the following operators:
- "!": logical "not"
- "&": logical "and"
- "|": logical "or"
"&" and "|" cannot be mixed without using parentheses.
Bean Definition Profiles
Bean definition profiles provide a mechanism in the core of the container that allows for registration of different beans in different environments, or according to different conditions. Beans can be associated with profiles and they are only registered if the associated profile or profiles are active. Note that if more than one valid candidates are found associated with the same active profile, the runtime fails with:
org.springframework.beans.factory.NoUniqueBeanDefinitionException: No qualifying bean of type 'playground.spring.profile.ColorAware' available: expected single matching bean but found 2: componentA,componentB
@Profile
The @Profile annotation is used to associate the component with one or more active profiles: the component annotated as such becomes eligible for registration, and will be instantiated and registered only if at least one of the profiles is associated with it is active.
import org.springframework.context.annotation.Profile;
import org.springframework.stereotype.Component;
...
@Component
@Profile("red")
public class ComponentA implements ColorAware {
...
}
...
@Component
@Profile("blue")
public class ComponentB implements ColorAware {
...
}
More than one profile can be specified:
@Component
@Profile({"yellow", "green"})
public class ComponentC implements ColorAware {
...
}
If a @Configuration class is marked with @Profile, all of the @Bean methods and @Import annotations are bypassed unless one or more of the specified profiles are active.
@Profile can be declared at method level in a @Configuration class. With @Profile on @Bean methods, a special scenario may apply: in the case of overloaded methods of the same Java method name (analogous to constructor overloading), a @Profile condition needs to be consistently declared on all overloaded methods. If the conditions are inconsistent, only the condition on the first declaration among the overloaded methods matters. Therefore, @Profile can not be used to select an overloaded method with a particular argument signature over another. Resolution between all factory methods for the same bean follows Spring’s constructor resolution algorithm at creation time. If you want to define alternative beans with different profile conditions, use distinct Java method names that point to the same bean name by using the @Bean name attribute. If the argument signatures are all the same (for example, all of the variants have no-arg factory methods), this is the only way to represent such an arrangement in a valid Java class in the first place, since there can only be one method of a particular name and argument signature.
@Profile can be used as meta-annotation, for the purpose of creating composed annotations: a custom annotation can be annotated with @Profie, and the custom annotation inherits the semantics provided by the @Profile annotation.
The association with one or more profile can be more complex when it is declared with a profile expression.