org.springframework.core.env

Interface ConfigurableEnvironment

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

      • addActiveProfile

        void addActiveProfile(java.lang.String profile)
        Add a profile to the current set of active profiles.
        Throws:
        java.lang.IllegalArgumentException - if the profile is null, empty or whitespace-only
        See Also:
        setActiveProfiles(java.lang.String...)
      • getSystemProperties

        java.util.Map<java.lang.String,java.lang.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.

      • getSystemEnvironment

        java.util.Map<java.lang.String,java.lang.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.

      • 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)