org.springframework.core.env Documentation Differences

This file contains all the changes in documentation in the package org.springframework.core.env as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Abstract base class for Environment implementations. Supports the notion of reserved default profile names and enables specifying active and default profiles through the .ACTIVE_PROFILES_PROPERTY_NAME and .DEFAULT_PROFILES_PROPERTY_NAME properties.

Concrete subclasses differ primarily on which PropertySource objects they add by default. {@code AbstractEnvironment} adds none. Subclasses should contribute property sources through the protected .customizePropertySources(MutablePropertySources) hook, while while clients should customize using ConfigurableEnvironment.getPropertySources() and and working against the MutablePropertySources API. See ConfigurableEnvironment Javadoc for usage examples. @author Chris Beams @since 3.1 @see ConfigurableEnvironment @see StandardEnvironment

Customize the set of PropertySource objects to be searched by this {@code Environment} during calls to .getProperty(String) and related methods.

Subclasses that override this method are encouraged to add property sources using MutablePropertySources.addLast(PropertySource) such that further subclasses may call {@code super.customizePropertySources()} with predictable results. For example:

 public class Level1Environment extends AbstractEnvironment {
     @Override
     protected void customizePropertySources(MutablePropertySources propertySources) {
         super.customizePropertySources(propertySources); // no-op from base class
         propertySources.addLast(new PropertySourceA(...));
         propertySources.addLast(new PropertySourceB(...));
     }
 }

 public class Level2Environment extends Level1Environment {
     @Override
     protected void customizePropertySources(MutablePropertySources propertySources) {
         super.customizePropertySources(propertySources); // add all from superclass
         propertySources.addLast(new PropertySourceC(...));
         propertySources.addLast(new PropertySourceD(...));
     }
 }
 

In this arrangement, properties will be resolved against sources A, B, C, D in that order. That is to say that property source "A" has precedence over property source "D". If the {@code Level2Environment} subclass wished to give property sources C and D higher precedence than A and B, it could simply call {@code super.customizePropertySources} after, rather than before adding its own:

 public class Level2Environment extends Level1Environment {
     @Override
     protected void customizePropertySources(MutablePropertySources propertySources) {
         propertySources.addLast(new PropertySourceC(...));
         propertySources.addLast(new PropertySourceD(...));
         super.customizePropertySources(propertySources); // add all from superclass
     }
 }
 

The search order is now C, D, A, B as desired.

Beyond these recommendations, subclasses may use any of the add*, {@code remove}, or {@code replace} methods exposed by MutablePropertySources in order to create the exact arrangement of property sources desired.

The base implementation in AbstractEnvironment.customizePropertySources registers no property sources.

Note that clients of any ConfigurableEnvironment may further customize property sources via the .getPropertySources() accessor, typically within an ApplicationContextInitializer. For example:

 ConfigurableEnvironment env = new StandardEnvironment();
 env.getPropertySources().addLast(new PropertySourceX(...));
 

A warning about instance variable access

Instance variables declared in subclasses and having default initial values should not be accessed from within this method. Due to Java object creation lifecycle constraints, any initial value will not yet be assigned when this callback is invoked by the .AbstractEnvironment() constructor, which may lead to a {@code NullPointerException} or other problems. If you need to access default values of instance variables, leave this method as a no-op and perform property source manipulation and instance variable access directly within the subclass constructor. Note that assigning values to instance variables is not problematic; it is only attempting to read default values that must be avoided. @see MutablePropertySources @see PropertySourcesPropertyResolver @see org.springframework.context.ApplicationContextInitializer

Validate the given profile, called internally prior to adding to the set of active or default profiles.

Subclasses may override to impose further restrictions on profile syntax. @throws IllegalArgumentException if the profile is null, empty or, whitespace-only only or begins with the profile NOT operator (!). @see #acceptsProfiles @see #addActiveProfile @see #setDefaultProfiles

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 {@code 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 {@code ApplicationContext}, it is important is important that any such {@code PropertySource} manipulations be performedperformed before the context's s refresh() method is called. This ensures that all property sources are available available during thethe container bootstrap process, including use by by org.springframework.context.support.PropertySourcesPlaceholderConfigurer propertyPropertySourcesPlaceholderConfigurer property placeholder configurers. @author Chris Beams @since 3.1 @see StandardEnvironment @see org.springframework.context.ConfigurableApplicationContext#getEnvironment

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, {@code null} will be returned and an INFO-level log message will be issued noting the exception.

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 {@code 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, {@code null} will be returned and an INFO-level log message will be issued noting the exception.

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.

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. @see #addActiveProfile @see #setDefaultProfiles @see org.springframework.context.annotation.Profile @see AbstractEnvironment#ACTIVE_PROFILES_PROPERTY_NAME @throws IllegalArgumentException if any profile is null, empty or whitespace-only

Return whether one or more of the given profiles is active or, in the case of no explicit active profiles, whether one or more of the given profiles is included in the set of default profiles profiles. If a profile begins with '!' the logic is inverted, i.e. the method will return true if the given profile is not active. For example, {@code env.acceptsProfiles("p1", "!p2")} will return true if profile 'p1' is active or 'p2' is not active. @throws IllegalArgumentException if called with zero arguments @throws IllegalArgumentException if any profile is null, empty or whitespace-only @see #getActiveProfiles @see #getDefaultProfiles

Return the property value associated with the given key, or {@code null} if the key cannot be resolved. @param key the property name to resolve @param TtargetType the expected type of the property value @see #getRequiredProperty(String, Class)

Return the property value associated with the given key, or {@code defaultValue} if the key cannot be resolved. @param key the property name to resolve @param TtargetType the expected type of the property value @param defaultValue the default value to return if no value is found @see #getRequiredProperty(String, Class)