org.springframework.core.env
Interface ConfigurableEnvironment

All Superinterfaces:

ConfigurablePropertyResolver, Environment, PropertyResolver

All Known Implementing Classes:

AbstractEnvironment, StandardEnvironment, StandardPortletEnvironment, StandardServletEnvironment

public interface ConfigurableEnvironment
extends Environment, ConfigurablePropertyResolver

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 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.

Since:

3.1

Author:

Chris Beams

See Also:

StandardEnvironment, ConfigurableApplicationContext.getEnvironment()

Method Summary

void	addActiveProfile(String profile) Add a profile to the current set of active profiles.
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.
Map<String,Object>	getSystemEnvironment() Return the value of System.getenv() if allowed by the current SecurityManager, otherwise return a map implementation that will attempt to access individual keys using calls to System.getenv(String).
Map<String,Object>	getSystemProperties() Return the value of System.getProperties() if allowed by the current SecurityManager, otherwise return a map implementation that will attempt to access individual keys using calls to System.getProperty(String).
void	setActiveProfiles(String... profiles) Specify the set of profiles active for this Environment.
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(java.lang.String...).

Methods inherited from interface org.springframework.core.env.Environment

acceptsProfiles, getActiveProfiles, getDefaultProfiles

Methods inherited from interface org.springframework.core.env.ConfigurablePropertyResolver

getConversionService, setConversionService, setPlaceholderPrefix, setPlaceholderSuffix, setRequiredProperties, setValueSeparator, validateRequiredProperties

Methods inherited from interface org.springframework.core.env.PropertyResolver

containsProperty, getProperty, getProperty, getProperty, getProperty, getPropertyAsClass, getRequiredProperty, getRequiredProperty, resolvePlaceholders, resolveRequiredPlaceholders

Method Detail

setActiveProfiles

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(java.lang.String) to add a profile while preserving the existing set.

Throws:

IllegalArgumentException - if any profile is null, empty or whitespace-only

See Also:

addActiveProfile(java.lang.String), setDefaultProfiles(java.lang.String...), Profile, AbstractEnvironment.ACTIVE_PROFILES_PROPERTY_NAME

addActiveProfile

void addActiveProfile(String profile)

Add a profile to the current set of active profiles.

Throws:

IllegalArgumentException - if the profile is null, empty or whitespace-only

See Also:

setActiveProfiles(java.lang.String...)

setDefaultProfiles

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(java.lang.String...).

Throws:

IllegalArgumentException - if any profile is null, empty or whitespace-only

See Also:

AbstractEnvironment.DEFAULT_PROFILES_PROPERTY_NAME

getPropertySources

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(org.springframework.core.env.MutablePropertySources)

getSystemEnvironment

Map<String,Object> getSystemEnvironment()

Return the value of System.getenv() if allowed by the current SecurityManager, otherwise return a map implementation that will attempt to access individual keys using calls to System.getenv(String).

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.

Calls to Map.get(Object) on the Map returned will never throw IllegalAccessException; in cases where the SecurityManager forbids access to a property, null will be returned and an INFO-level log message will be issued noting the exception.

getSystemProperties

Map<String,Object> getSystemProperties()

Return the value of System.getProperties() if allowed by the current SecurityManager, otherwise return a map implementation that will attempt to access individual keys using calls to System.getProperty(String).

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.

Calls to Map.get(Object) on the Map returned will never throw IllegalAccessException; in cases where the SecurityManager forbids access to a property, null will be returned and an INFO-level log message will be issued noting the exception.