/*
* Copyright 2002-2018 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.core.env;
import 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, 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. Author: Chris Beams See Also: - StandardEnvironment
- getEnvironment.getEnvironment
Since: 3.1
/**
* Configuration interface to be implemented by most if not all {@link 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 {@link ConfigurablePropertyResolver}
* superinterface.
*
* <h2>Manipulating property sources</h2>
* <p>Property sources may be removed, reordered, or replaced; and additional
* property sources may be added using the {@link MutablePropertySources}
* instance returned from {@link #getPropertySources()}. The following examples
* are against the {@link StandardEnvironment} implementation of
* {@code ConfigurableEnvironment}, but are generally applicable to any implementation,
* though particular default property sources may differ.
*
* <h4>Example: adding a new property source with highest search priority</h4>
* <pre class="code">
* 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));
* </pre>
*
* <h4>Example: removing the default system properties property source</h4>
* <pre class="code">
* MutablePropertySources propertySources = environment.getPropertySources();
* propertySources.remove(StandardEnvironment.SYSTEM_PROPERTIES_PROPERTY_SOURCE_NAME)
* </pre>
*
* <h4>Example: mocking the system environment for testing purposes</h4>
* <pre class="code">
* MutablePropertySources propertySources = environment.getPropertySources();
* MockPropertySource mockEnvVars = new MockPropertySource().withProperty("xyz", "myValue");
* propertySources.replace(StandardEnvironment.SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME, mockEnvVars);
* </pre>
*
* When an {@link Environment} is being used by an {@code ApplicationContext}, it is
* important that any such {@code PropertySource} manipulations be performed
* <em>before</em> the context's {@link
* org.springframework.context.support.AbstractApplicationContext#refresh() refresh()}
* method is called. This ensures that all property sources are available during the
* container bootstrap process, including use by {@linkplain
* org.springframework.context.support.PropertySourcesPlaceholderConfigurer property
* placeholder configurers}.
*
* @author Chris Beams
* @since 3.1
* @see StandardEnvironment
* @see org.springframework.context.ConfigurableApplicationContext#getEnvironment
*/
public interface ConfigurableEnvironment extends Environment, ConfigurablePropertyResolver {
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.
Throws: - IllegalArgumentException – if any profile is null, empty or whitespace-only
See Also:
/**
* Specify the set of profiles active for this {@code Environment}. Profiles are
* evaluated during container bootstrap to determine whether bean definitions
* should be registered with the container.
* <p>Any existing active profiles will be replaced with the given arguments; call
* with zero arguments to clear the current set of active profiles. Use
* {@link #addActiveProfile} to add a profile while preserving the existing set.
* @throws IllegalArgumentException if any profile is null, empty or whitespace-only
* @see #addActiveProfile
* @see #setDefaultProfiles
* @see org.springframework.context.annotation.Profile
* @see AbstractEnvironment#ACTIVE_PROFILES_PROPERTY_NAME
*/
void setActiveProfiles(String... profiles);
Add a profile to the current set of active profiles.
Throws: - IllegalArgumentException – if the profile is null, empty or whitespace-only
See Also:
/**
* Add a profile to the current set of active profiles.
* @throws IllegalArgumentException if the profile is null, empty or whitespace-only
* @see #setActiveProfiles
*/
void addActiveProfile(String profile);
Specify the set of profiles to be made active by default if no other profiles are explicitly made active through setActiveProfiles. Throws: - IllegalArgumentException – if any profile is null, empty or whitespace-only
See Also:
/**
* Specify the set of profiles to be made active by default if no other profiles
* are explicitly made active through {@link #setActiveProfiles}.
* @throws IllegalArgumentException if any profile is null, empty or whitespace-only
* @see AbstractEnvironment#DEFAULT_PROFILES_PROPERTY_NAME
*/
void setDefaultProfiles(String... profiles);
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:
/**
* Return the {@link PropertySources} for this {@code Environment} in mutable form,
* allowing for manipulation of the set of {@link PropertySource} objects that should
* be searched when resolving properties against this {@code Environment} object.
* The various {@link MutablePropertySources} methods such as
* {@link MutablePropertySources#addFirst addFirst},
* {@link MutablePropertySources#addLast addLast},
* {@link MutablePropertySources#addBefore addBefore} and
* {@link MutablePropertySources#addAfter 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 AbstractEnvironment#customizePropertySources
*/
MutablePropertySources getPropertySources();
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.
/**
* Return the value of {@link System#getProperties()} if allowed by the current
* {@link SecurityManager}, otherwise return a map implementation that will attempt
* to access individual keys using calls to {@link System#getProperty(String)}.
* <p>Note that most {@code Environment} implementations will include this system
* properties map as a default {@link PropertySource} to be searched. Therefore, it is
* recommended that this method not be used directly unless bypassing other property
* sources is expressly intended.
* <p>Calls to {@link Map#get(Object)} on the Map returned will never throw
* {@link IllegalAccessException}; in cases where the SecurityManager forbids access
* to a property, {@code null} will be returned and an INFO-level log message will be
* issued noting the exception.
*/
Map<String, Object> getSystemProperties();
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.
/**
* Return the value of {@link System#getenv()} if allowed by the current
* {@link SecurityManager}, otherwise return a map implementation that will attempt
* to access individual keys using calls to {@link System#getenv(String)}.
* <p>Note that most {@link Environment} implementations will include this system
* environment map as a default {@link PropertySource} to be searched. Therefore, it
* is recommended that this method not be used directly unless bypassing other
* property sources is expressly intended.
* <p>Calls to {@link Map#get(Object)} on the Map returned will never throw
* {@link IllegalAccessException}; in cases where the SecurityManager forbids access
* to a property, {@code null} will be returned and an INFO-level log message will be
* issued noting the exception.
*/
Map<String, Object> getSystemEnvironment();
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.
Params: - parent – the environment to merge with
See Also: - setParent.setParent
Since: 3.1.2
/**
* Append the given parent environment's active profiles, default profiles and
* property sources to this (child) environment's respective collections of each.
* <p>For any identically-named {@code 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.
* <p>Active and default profile names are also filtered for duplicates, to avoid
* confusion and redundant storage.
* <p>The parent environment remains unmodified in any case. Note that any changes to
* the parent environment occurring after the call to {@code merge} will not be
* reflected in the child. Therefore, care should be taken to configure parent
* property sources and profile information prior to calling {@code merge}.
* @param parent the environment to merge with
* @since 3.1.2
* @see org.springframework.context.support.AbstractApplicationContext#setParent
*/
void merge(ConfigurableEnvironment parent);
}