diff --git a/org.springframework.core/src/main/java/org/springframework/core/env/ConfigurableEnvironment.java b/org.springframework.core/src/main/java/org/springframework/core/env/ConfigurableEnvironment.java index d9b5e6dc243..af934ba875b 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/env/ConfigurableEnvironment.java +++ b/org.springframework.core/src/main/java/org/springframework/core/env/ConfigurableEnvironment.java @@ -31,7 +31,7 @@ import java.util.Map; public interface ConfigurableEnvironment extends Environment, ConfigurablePropertyResolver { /** - * Specify the set of profiles active for this Environment. Profiles are + * 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. * @@ -66,32 +66,36 @@ public interface ConfigurableEnvironment extends Environment, ConfigurableProper MutablePropertySources getPropertySources(); /** - * 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)}. + * 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)}. * - *

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. + *

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. * - *

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. + *

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 getSystemEnvironment(); /** - * 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)}. + * 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)}. * - *

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. + *

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. * - *

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. + *

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 getSystemProperties(); diff --git a/org.springframework.core/src/main/java/org/springframework/core/env/Environment.java b/org.springframework.core/src/main/java/org/springframework/core/env/Environment.java index 947268fa709..e6aeaa35358 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/env/Environment.java +++ b/org.springframework.core/src/main/java/org/springframework/core/env/Environment.java @@ -18,45 +18,49 @@ package org.springframework.core.env; /** * Interface representing the environment in which the current application is running. - * Models two key aspects of the application environment: - *

    - *
  1. profiles
    2. - *
  2. properties
    3. - *
+ * Models two key aspects of the application environment: profiles and + * properties. * - * A profile is a named, logical group of bean definitions to be registered with the - * container only if the given profile is active. Beans may be assigned to a profile - * whether defined in XML or annotations; see the spring-beans 3.1 schema or the {@link - * org.springframework.context.annotation.Profile @Profile} annotation for syntax details. - * The role of the Environment object with relation to profiles is in determining which profiles - * (if any) are currently {@linkplain #getActiveProfiles active}, and which profiles (if any) - * should be {@linkplain #getDefaultProfiles active by default}. + *

A profile is a named, logical group of bean definitions to be registered + * with the container only if the given profile is active. Beans may be assigned + * to a profile whether defined in XML or via annotations; see the spring-beans 3.1 schema + * or the {@link org.springframework.context.annotation.Profile @Profile} annotation for + * syntax details. The role of the {@code Environment} object with relation to profiles is + * in determining which profiles (if any) are currently {@linkplain #getActiveProfiles + * active}, and which profiles (if any) should be {@linkplain #getDefaultProfiles active + * by default}. * - *

Properties play an important role in almost all applications, and may originate - * from a variety of sources: properties files, JVM system properties, system environment - * variables, JNDI, servlet context parameters, ad-hoc Properties objects, Maps, and so on. - * The role of the environment object with relation to properties is to provide the user with a - * convenient service interface for configuring property sources and resolving properties from them. + *

Properties play an important role in almost all applications, and may + * originate from a variety of sources: properties files, JVM system properties, system + * environment variables, JNDI, servlet context parameters, ad-hoc Properties objects, + * Maps, and so on. The role of the environment object with relation to properties is to + * provide the user with a convenient service interface for configuring property sources + * and resolving properties from them. * *

Beans managed within an ApplicationContext may register to be {@link - * org.springframework.context.EnvironmentAware EnvironmentAware}, where they can query profile state - * or resolve properties directly. + * org.springframework.context.EnvironmentAware EnvironmentAware} or {@code @Inject} the + * {@code Environment} in order to query profile state or resolve properties directly. * - *

More commonly, beans will not interact with the Environment directly, but will have ${...} - * property values replaced by a property placeholder configurer such as {@link - * org.springframework.context.support.PropertySourcesPlaceholderConfigurer - * PropertySourcesPlaceholderConfigurer}, which itself is EnvironmentAware, and as of Spring 3.1 is - * registered by default when using {@code }. + *

In most cases, however, application-level beans should not need to interact with the + * {@code Environment} directly but instead may have to have ${...} property + * values replaced by a property placeholder configurer such as + * {@link org.springframework.context.support.PropertySourcesPlaceholderConfigurer + * PropertySourcesPlaceholderConfigurer}, which itself is {@code EnvironmentAware} and + * as of Spring 3.1 is registered by default when using + * {@code }. * - *

Configuration of the environment object must be done through the {@link ConfigurableEnvironment} - * interface, returned from all AbstractApplicationContext subclass getEnvironment() methods. See - * {@link DefaultEnvironment} for several examples of using the ConfigurableEnvironment interface - * to manipulate property sources prior to application context refresh(). + *

Configuration of the environment object must be done through the + * {@link ConfigurableEnvironment} interface, returned from all + * {@code AbstractApplicationContext} subclass {@code getEnvironment()} methods. See + * {@link DefaultEnvironment} for several examples of using the ConfigurableEnvironment + * interface to manipulate property sources prior to application context refresh(). * * @author Chris Beams * @since 3.1 + * @see PropertyResolver * @see EnvironmentCapable * @see ConfigurableEnvironment + * @see AbstractEnvironment * @see DefaultEnvironment * @see org.springframework.context.EnvironmentAware * @see org.springframework.context.ConfigurableApplicationContext#getEnvironment diff --git a/org.springframework.core/src/main/java/org/springframework/core/env/PropertyResolver.java b/org.springframework.core/src/main/java/org/springframework/core/env/PropertyResolver.java index c5d2aab7df1..60b8da43ff0 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/env/PropertyResolver.java +++ b/org.springframework.core/src/main/java/org/springframework/core/env/PropertyResolver.java @@ -21,11 +21,14 @@ package org.springframework.core.env; * * @author Chris Beams * @since 3.1 + * @see Environment + * @see PropertySourcesPropertyResolver */ public interface PropertyResolver { /** - * Return whether the given property key is available for resolution. + * Return whether the given property key is available for resolution, i.e., + * the value for the given key is not {@code null}. */ boolean containsProperty(String key); diff --git a/org.springframework.core/src/main/java/org/springframework/core/env/PropertySourcesPropertyResolver.java b/org.springframework.core/src/main/java/org/springframework/core/env/PropertySourcesPropertyResolver.java index eede760b95b..333056f3cbf 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/env/PropertySourcesPropertyResolver.java +++ b/org.springframework.core/src/main/java/org/springframework/core/env/PropertySourcesPropertyResolver.java @@ -27,6 +27,9 @@ import org.springframework.util.ClassUtils; * * @author Chris Beams * @since 3.1 + * @see PropertySource + * @see PropertySources + * @see AbstractEnvironment */ public class PropertySourcesPropertyResolver extends AbstractPropertyResolver {