public abstract class AbstractEnvironment extends Object implements ConfigurableEnvironment
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. AbstractEnvironment
adds none. Subclasses should contribute
property sources through the protected customizePropertySources(MutablePropertySources)
hook, while clients should customize using ConfigurableEnvironment.getPropertySources()
and working against the MutablePropertySources
API.
See ConfigurableEnvironment
javadoc for usage examples.
ConfigurableEnvironment
,
StandardEnvironment
Modifier and Type | Field and Description |
---|---|
static String |
ACTIVE_PROFILES_PROPERTY_NAME
Name of property to set to specify active profiles: "spring.profiles.active".
|
static String |
DEFAULT_PROFILES_PROPERTY_NAME
Name of property to set to specify profiles active by default: "spring.profiles.default".
|
static String |
IGNORE_GETENV_PROPERTY_NAME
System property that instructs Spring to ignore system environment variables,
i.e.
|
protected Log |
logger |
protected static String |
RESERVED_DEFAULT_PROFILE_NAME
Name of reserved default profile name: "default".
|
Constructor and Description |
---|
AbstractEnvironment()
Create a new
Environment instance, calling back to
customizePropertySources(MutablePropertySources) during construction to
allow subclasses to contribute or manipulate PropertySource instances as
appropriate. |
Modifier and Type | Method and Description |
---|---|
boolean |
acceptsProfiles(String... profiles)
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.
|
void |
addActiveProfile(String profile)
Add a profile to the current set of active profiles.
|
boolean |
containsProperty(String key)
Return whether the given property key is available for resolution, i.e.,
the value for the given key is not
null . |
protected void |
customizePropertySources(MutablePropertySources propertySources)
Customize the set of
PropertySource objects to be searched by this
Environment during calls to getProperty(String) and related
methods. |
protected Set<String> |
doGetActiveProfiles()
Return the set of active profiles as explicitly set through
setActiveProfiles(java.lang.String...) or if the current set of active profiles
is empty, check for the presence of the "spring.profiles.active"
property and assign its value to the set of active profiles. |
protected Set<String> |
doGetDefaultProfiles()
Return the set of default profiles explicitly set via
setDefaultProfiles(String...) or if the current set of default profiles
consists only of reserved default
profiles, then check for the presence of the
"spring.profiles.default" property and assign its value (if any)
to the set of default profiles. |
String[] |
getActiveProfiles()
Return the set of profiles explicitly made active for this environment.
|
ConfigurableConversionService |
getConversionService() |
String[] |
getDefaultProfiles()
Return the set of profiles to be active by default when no active profiles have
been set explicitly.
|
String |
getProperty(String key)
Return the property value associated with the given key, or
null
if the key cannot be resolved. |
<T> T |
getProperty(String key,
Class<T> targetType)
Return the property value associated with the given key, or
null
if the key cannot be resolved. |
<T> T |
getProperty(String key,
Class<T> targetType,
T defaultValue)
Return the property value associated with the given key, or
defaultValue if the key cannot be resolved. |
String |
getProperty(String key,
String defaultValue)
Return the property value associated with the given key, or
defaultValue if the key cannot be resolved. |
<T> Class<T> |
getPropertyAsClass(String key,
Class<T> targetType)
Convert the property value associated with the given key to a
Class
of type T or null if the key cannot be resolved. |
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. |
String |
getRequiredProperty(String key)
Return the property value associated with the given key (never
null ). |
<T> T |
getRequiredProperty(String key,
Class<T> targetType)
Return the property value associated with the given key, converted to the given
targetType (never
null ). |
protected Set<String> |
getReservedDefaultProfiles()
Return the set of reserved default profile names.
|
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) . |
protected boolean |
isProfileActive(String profile)
Return whether the given profile is active, or if active profiles are empty
whether the profile should be active by default.
|
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.
|
String |
resolvePlaceholders(String text)
Resolve ${...} placeholders in the given text, replacing them with corresponding
property values as resolved by
PropertyResolver.getProperty(java.lang.String) . |
String |
resolveRequiredPlaceholders(String text)
Resolve ${...} placeholders in the given text, replacing them with corresponding
property values as resolved by
PropertyResolver.getProperty(java.lang.String) . |
void |
setActiveProfiles(String... profiles)
Specify the set of profiles active for this
Environment . |
void |
setConversionService(ConfigurableConversionService conversionService)
Set the
ConfigurableConversionService to be used when performing type
conversions on properties. |
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...) . |
void |
setIgnoreUnresolvableNestedPlaceholders(boolean ignoreUnresolvableNestedPlaceholders)
Set whether to throw an exception when encountering an unresolvable placeholder
nested within the value of a given property.
|
void |
setPlaceholderPrefix(String placeholderPrefix)
Set the prefix that placeholders replaced by this resolver must begin with.
|
void |
setPlaceholderSuffix(String placeholderSuffix)
Set the suffix that placeholders replaced by this resolver must end with.
|
void |
setRequiredProperties(String... requiredProperties)
Specify which properties must be present, to be verified by
ConfigurablePropertyResolver.validateRequiredProperties() . |
void |
setValueSeparator(String valueSeparator)
Specify the separating character between the placeholders replaced by this
resolver and their associated default value, or
null if no such
special character should be processed as a value separator. |
protected boolean |
suppressGetenvAccess()
Determine whether to suppress
System.getenv() /System.getenv(String)
access for the purposes of getSystemEnvironment() . |
String |
toString() |
protected void |
validateProfile(String profile)
Validate the given profile, called internally prior to adding to the set of
active or default profiles.
|
void |
validateRequiredProperties()
Validate that each of the properties specified by
ConfigurablePropertyResolver.setRequiredProperties(java.lang.String...) is present and resolves to a
non-null value. |
public static final String IGNORE_GETENV_PROPERTY_NAME
System.getenv()
.
The default is "false", falling back to system environment variable checks if a
Spring environment property (e.g. a placeholder in a configuration String) isn't
resolvable otherwise. Consider switching this flag to "true" if you experience
log warnings from getenv
calls coming from Spring, e.g. on WebSphere
with strict SecurityManager settings and AccessControlExceptions warnings.
suppressGetenvAccess()
,
Constant Field Valuespublic static final String ACTIVE_PROFILES_PROPERTY_NAME
Note that certain shell environments such as Bash disallow the use of the period
character in variable names. Assuming that Spring's SystemEnvironmentPropertySource
is in use, this property may be specified as an environment variable as
SPRING_PROFILES_ACTIVE
.
public static final String DEFAULT_PROFILES_PROPERTY_NAME
Note that certain shell environments such as Bash disallow the use of the period
character in variable names. Assuming that Spring's SystemEnvironmentPropertySource
is in use, this property may be specified as an environment variable as
SPRING_PROFILES_DEFAULT
.
protected static final String RESERVED_DEFAULT_PROFILE_NAME
protected final Log logger
public AbstractEnvironment()
Environment
instance, calling back to
customizePropertySources(MutablePropertySources)
during construction to
allow subclasses to contribute or manipulate PropertySource
instances as
appropriate.protected void customizePropertySources(MutablePropertySources propertySources)
PropertySource
objects to be searched by this
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 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
Level2Environment
subclass wished to give property sources C
and D higher precedence than A and B, it could simply call
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*
,
remove
, or replace
methods exposed by MutablePropertySources
in order to create the exact arrangement of property sources desired.
The base implementation 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(...));
AbstractEnvironment()
constructor, which may
lead to a 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.protected Set<String> getReservedDefaultProfiles()
public String[] getActiveProfiles()
Environment
ConfigurableEnvironment.setActiveProfiles(String...)
.
If no profiles have explicitly been specified as active, then any default profiles will automatically be activated.
getActiveProfiles
in interface Environment
Environment.getDefaultProfiles()
,
ConfigurableEnvironment.setActiveProfiles(java.lang.String...)
,
ACTIVE_PROFILES_PROPERTY_NAME
protected Set<String> doGetActiveProfiles()
setActiveProfiles(java.lang.String...)
or if the current set of active profiles
is empty, check for the presence of the "spring.profiles.active"
property and assign its value to the set of active profiles.getActiveProfiles()
,
ACTIVE_PROFILES_PROPERTY_NAME
public void setActiveProfiles(String... profiles)
ConfigurableEnvironment
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
ConfigurableEnvironment.addActiveProfile(java.lang.String)
to add a profile while preserving the existing set.
public void addActiveProfile(String profile)
ConfigurableEnvironment
addActiveProfile
in interface ConfigurableEnvironment
ConfigurableEnvironment.setActiveProfiles(java.lang.String...)
public String[] getDefaultProfiles()
Environment
getDefaultProfiles
in interface Environment
Environment.getActiveProfiles()
,
ConfigurableEnvironment.setDefaultProfiles(java.lang.String...)
,
DEFAULT_PROFILES_PROPERTY_NAME
protected Set<String> doGetDefaultProfiles()
setDefaultProfiles(String...)
or if the current set of default profiles
consists only of reserved default
profiles, then check for the presence of the
"spring.profiles.default" property and assign its value (if any)
to the set of default profiles.public void setDefaultProfiles(String... profiles)
setActiveProfiles(java.lang.String...)
.
Calling this method removes overrides any reserved default profiles that may have been added during construction of the environment.
setDefaultProfiles
in interface ConfigurableEnvironment
AbstractEnvironment()
,
getReservedDefaultProfiles()
public boolean acceptsProfiles(String... profiles)
Environment
env.acceptsProfiles("p1", "!p2")will return
true
if profile 'p1' is active or 'p2' is not active.acceptsProfiles
in interface Environment
Environment.getActiveProfiles()
,
Environment.getDefaultProfiles()
protected boolean isProfileActive(String profile)
IllegalArgumentException
- per validateProfile(String)
protected void validateProfile(String profile)
Subclasses may override to impose further restrictions on profile syntax.
IllegalArgumentException
- if the profile is null, empty, whitespace-only or
begins with the profile NOT operator (!).acceptsProfiles(java.lang.String...)
,
addActiveProfile(java.lang.String)
,
setDefaultProfiles(java.lang.String...)
public MutablePropertySources getPropertySources()
ConfigurableEnvironment
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.getPropertySources
in interface ConfigurableEnvironment
customizePropertySources(org.springframework.core.env.MutablePropertySources)
public Map<String,Object> getSystemEnvironment()
ConfigurableEnvironment
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.
getSystemEnvironment
in interface ConfigurableEnvironment
protected boolean suppressGetenvAccess()
System.getenv()
/System.getenv(String)
access for the purposes of getSystemEnvironment()
.
If this method returns true
, an empty dummy Map will be used instead
of the regular system environment Map, never even trying to call getenv
and therefore avoiding security manager warnings (if any).
The default implementation checks for the "spring.getenv.ignore" system property,
returning true
if its value equals "true" in any case.
public Map<String,Object> getSystemProperties()
ConfigurableEnvironment
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.
getSystemProperties
in interface ConfigurableEnvironment
public void merge(ConfigurableEnvironment parent)
ConfigurableEnvironment
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
.
merge
in interface ConfigurableEnvironment
parent
- the environment to merge withAbstractApplicationContext.setParent(org.springframework.context.ApplicationContext)
public ConfigurableConversionService getConversionService()
getConversionService
in interface ConfigurablePropertyResolver
ConfigurableConversionService
used when performing type
conversions on properties.
The configurable nature of the returned conversion service allows for
the convenient addition and removal of individual Converter
instances:
ConfigurableConversionService cs = env.getConversionService(); cs.addConverter(new FooConverter());
PropertyResolver.getProperty(String, Class)
,
ConverterRegistry.addConverter(org.springframework.core.convert.converter.Converter<?, ?>)
public void setConversionService(ConfigurableConversionService conversionService)
ConfigurablePropertyResolver
ConfigurableConversionService
to be used when performing type
conversions on properties.
Note: as an alternative to fully replacing the ConversionService
, consider adding or removing individual Converter
instances by drilling into ConfigurablePropertyResolver.getConversionService()
and calling methods
such as #addConverter
.
public void setPlaceholderPrefix(String placeholderPrefix)
ConfigurablePropertyResolver
setPlaceholderPrefix
in interface ConfigurablePropertyResolver
public void setPlaceholderSuffix(String placeholderSuffix)
ConfigurablePropertyResolver
setPlaceholderSuffix
in interface ConfigurablePropertyResolver
public void setValueSeparator(String valueSeparator)
ConfigurablePropertyResolver
null
if no such
special character should be processed as a value separator.setValueSeparator
in interface ConfigurablePropertyResolver
public void setIgnoreUnresolvableNestedPlaceholders(boolean ignoreUnresolvableNestedPlaceholders)
ConfigurablePropertyResolver
false
value indicates strict
resolution, i.e. that an exception will be thrown. A true
value indicates
that unresolvable nested placeholders should be passed through in their unresolved
${...} form.
Implementations of PropertyResolver.getProperty(String)
and its variants must inspect
the value set here to determine correct behavior when property values contain
unresolvable placeholders.
setIgnoreUnresolvableNestedPlaceholders
in interface ConfigurablePropertyResolver
public void setRequiredProperties(String... requiredProperties)
ConfigurablePropertyResolver
ConfigurablePropertyResolver.validateRequiredProperties()
.setRequiredProperties
in interface ConfigurablePropertyResolver
public void validateRequiredProperties() throws MissingRequiredPropertiesException
ConfigurablePropertyResolver
ConfigurablePropertyResolver.setRequiredProperties(java.lang.String...)
is present and resolves to a
non-null
value.validateRequiredProperties
in interface ConfigurablePropertyResolver
MissingRequiredPropertiesException
- if any of the required
properties are not resolvable.public boolean containsProperty(String key)
PropertyResolver
null
.containsProperty
in interface PropertyResolver
public String getProperty(String key)
PropertyResolver
null
if the key cannot be resolved.getProperty
in interface PropertyResolver
key
- the property name to resolvePropertyResolver.getProperty(String, String)
,
PropertyResolver.getProperty(String, Class)
,
PropertyResolver.getRequiredProperty(String)
public String getProperty(String key, String defaultValue)
PropertyResolver
defaultValue
if the key cannot be resolved.getProperty
in interface PropertyResolver
key
- the property name to resolvedefaultValue
- the default value to return if no value is foundPropertyResolver.getRequiredProperty(String)
,
PropertyResolver.getProperty(String, Class)
public <T> T getProperty(String key, Class<T> targetType)
PropertyResolver
null
if the key cannot be resolved.getProperty
in interface PropertyResolver
key
- the property name to resolvetargetType
- the expected type of the property valuePropertyResolver.getRequiredProperty(String, Class)
public <T> T getProperty(String key, Class<T> targetType, T defaultValue)
PropertyResolver
defaultValue
if the key cannot be resolved.getProperty
in interface PropertyResolver
key
- the property name to resolvetargetType
- the expected type of the property valuedefaultValue
- the default value to return if no value is foundPropertyResolver.getRequiredProperty(String, Class)
public <T> Class<T> getPropertyAsClass(String key, Class<T> targetType)
PropertyResolver
Class
of type T
or null
if the key cannot be resolved.getPropertyAsClass
in interface PropertyResolver
PropertyResolver.getProperty(String, Class)
public String getRequiredProperty(String key) throws IllegalStateException
PropertyResolver
null
).getRequiredProperty
in interface PropertyResolver
IllegalStateException
- if the key cannot be resolvedPropertyResolver.getRequiredProperty(String, Class)
public <T> T getRequiredProperty(String key, Class<T> targetType) throws IllegalStateException
PropertyResolver
null
).getRequiredProperty
in interface PropertyResolver
IllegalStateException
- if the given key cannot be resolvedpublic String resolvePlaceholders(String text)
PropertyResolver
PropertyResolver.getProperty(java.lang.String)
. Unresolvable placeholders with
no default value are ignored and passed through unchanged.resolvePlaceholders
in interface PropertyResolver
text
- the String to resolvenull
)PropertyResolver.resolveRequiredPlaceholders(java.lang.String)
,
SystemPropertyUtils.resolvePlaceholders(String)
public String resolveRequiredPlaceholders(String text) throws IllegalArgumentException
PropertyResolver
PropertyResolver.getProperty(java.lang.String)
. Unresolvable placeholders with
no default value will cause an IllegalArgumentException to be thrown.resolveRequiredPlaceholders
in interface PropertyResolver
null
)IllegalArgumentException
- if given text is null
or if any placeholders are unresolvableSystemPropertyUtils.resolvePlaceholders(String, boolean)