ConfigurableEnvironment (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.core.env

## Interface ConfigurableEnvironment

- All Superinterfaces:
    ConfigurablePropertyResolver, Environment, PropertyResolver
  All Known Subinterfaces:
    ConfigurableWebEnvironment
  All Known Implementing Classes:
    AbstractEnvironment, MockEnvironment, 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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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` | `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.
    `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, setIgnoreUnresolvableNestedPlaceholders, 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.

    - #### merge

          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` - the environment to merge with
      Since:
        3.1.2
      See Also:
        `AbstractApplicationContext.setParent(org.springframework.context.ApplicationContext)`