Top Description Methods
org.springframework.core.env

public Interface ConfigurableEnvironment

extends Environment, ConfigurablePropertyResolver
Known Direct Implementers
org.springframework.core.env.AbstractEnvironment
Imports
java.util.Map
Configuration interface to be implemented by most if not all Environment types. Provides facilities for setting active and default profiles and manipulating underlying property sources. Allows clients to set and validate required properties, customize the conversion service and more through the ConfigurablePropertyResolver superinterface.

Manipulating property sources

Property sources may be removed, reordered, or replaced; and additional property sources may be added using the MutablePropertySources instance returned from getPropertySources(). The following examples are against the StandardEnvironment implementation of ConfigurableEnvironment, but are generally applicable to any implementation, though particular default property sources may differ.

Example: adding a new property source with highest search priority

ConfigurableEnvironment environment = new StandardEnvironment();
MutablePropertySources propertySources = environment.getPropertySources();
Map<String, Object> myMap = new HashMap<>();
myMap.put("xyz", "myValue");
propertySources.addFirst(new MapPropertySource("MY_MAP", myMap));

Example: removing the default system properties property source

MutablePropertySources propertySources = environment.getPropertySources();
propertySources.remove(StandardEnvironment.SYSTEM_PROPERTIES_PROPERTY_SOURCE_NAME)

Example: mocking the system environment for testing purposes

MutablePropertySources propertySources = environment.getPropertySources();
MockPropertySource mockEnvVars = new MockPropertySource().withProperty("xyz", "myValue");
propertySources.replace(StandardEnvironment.SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME, mockEnvVars);
When an Environment is being used by an ApplicationContext, it is important that any such PropertySource manipulations be performed before the context's refresh() method is called. This ensures that all property sources are available during the container bootstrap process, including use by property placeholder configurers.
Author
Chris Beams
Since
3.1
See Also
StandardEnvironment, org.springframework.context.ConfigurableApplicationContext#getEnvironment

Method Summary

Modifier and TypeMethod and Description
public void
addActiveProfile(String profile)

Add a profile to the current set of active profiles.

public MutablePropertySources
getPropertySources()

Return the PropertySources for this Environment in mutable form, allowing for manipulation of the set of PropertySource objects that should be searched when resolving properties against this Environment object.

public Map<String, Object>
getSystemEnvironment()

Return the value of System#getenv().

public Map<String, Object>
getSystemProperties()

Return the value of System#getProperties().

public void
merge(ConfigurableEnvironment
the environment to merge with
parent)

Append the given parent environment's active profiles, default profiles and property sources to this (child) environment's respective collections of each.

public void
setActiveProfiles(String... profiles)

Specify the set of profiles active for this Environment.

public void
setDefaultProfiles(String... profiles)

Specify the set of profiles to be made active by default if no other profiles are explicitly made active through setActiveProfiles.

Inherited from org.springframework.core.env.ConfigurablePropertyResolver:
getConversionServicesetConversionServicesetIgnoreUnresolvableNestedPlaceholderssetPlaceholderPrefixsetPlaceholderSuffixsetRequiredPropertiessetValueSeparatorvalidateRequiredProperties
Inherited from org.springframework.core.env.Environment:
acceptsProfilesacceptsProfilesgetActiveProfilesgetDefaultProfilesmatchesProfiles

Method Detail

addActiveProfileback to summary
public void addActiveProfile(String profile)

Add a profile to the current set of active profiles.

Exceptions
IllegalArgumentException:
if the profile is null, empty or whitespace-only
See Also
setActiveProfiles
getPropertySourcesback to summary
public MutablePropertySources getPropertySources()

Return the PropertySources for this Environment in mutable form, allowing for manipulation of the set of PropertySource objects that should be searched when resolving properties against this Environment object. The various MutablePropertySources methods such as addFirst, addLast, addBefore and addAfter allow for fine-grained control over property source ordering. This is useful, for example, in ensuring that certain user-defined property sources have search precedence over default property sources such as the set of system properties or the set of system environment variables.

See Also
AbstractEnvironment#customizePropertySources
getSystemEnvironmentback to summary
public Map<String, Object> getSystemEnvironment()

Return the value of System#getenv().

Note that most Environment implementations will include this system environment map as a default PropertySource to be searched. Therefore, it is recommended that this method not be used directly unless bypassing other property sources is expressly intended.

getSystemPropertiesback to summary
public Map<String, Object> getSystemProperties()

Return the value of System#getProperties().

Note that most Environment implementations will include this system properties map as a default PropertySource to be searched. Therefore, it is recommended that this method not be used directly unless bypassing other property sources is expressly intended.

mergeback to summary
public void merge(ConfigurableEnvironment parent)

Append the given parent environment's active profiles, default profiles and property sources to this (child) environment's respective collections of each.

For any identically-named PropertySource instance existing in both parent and child, the child instance is to be preserved and the parent instance discarded. This has the effect of allowing overriding of property sources by the child as well as avoiding redundant searches through common property source types, e.g. system environment and system properties.

Active and default profile names are also filtered for duplicates, to avoid confusion and redundant storage.

The parent environment remains unmodified in any case. Note that any changes to the parent environment occurring after the call to merge will not be reflected in the child. Therefore, care should be taken to configure parent property sources and profile information prior to calling merge.

Parameters
parent:ConfigurableEnvironment

the environment to merge with

Since
3.1.2
See Also
org.springframework.context.support.AbstractApplicationContext#setParent
setActiveProfilesback to summary
public void setActiveProfiles(String... profiles)

Specify the set of profiles active for this Environment. Profiles are evaluated during container bootstrap to determine whether bean definitions should be registered with the container.

Any existing active profiles will be replaced with the given arguments; call with zero arguments to clear the current set of active profiles. Use addActiveProfile to add a profile while preserving the existing set.

Exceptions
IllegalArgumentException:
if any profile is null, empty or whitespace-only
See Also
addActiveProfile, setDefaultProfiles, org.springframework.context.annotation.Profile, AbstractEnvironment#ACTIVE_PROFILES_PROPERTY_NAME
setDefaultProfilesback to summary
public void setDefaultProfiles(String... profiles)

Specify the set of profiles to be made active by default if no other profiles are explicitly made active through setActiveProfiles.

Exceptions
IllegalArgumentException:
if any profile is null, empty or whitespace-only
See Also
AbstractEnvironment#DEFAULT_PROFILES_PROPERTY_NAME