Polish Environment-related Javadoc

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@4336 50f2f4bb-b051-0410-bef5-90022cba6387

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},
+	 * Return the value of {@link System#getenv()} if allowed by the current
-	 * otherwise return a map implementation that will attempt to access individual keys using calls to
+	 * {@link SecurityManager}, otherwise return a map implementation that will attempt
-	 * {@link System#getenv(String)}.
+	 * 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
+	 * <p>Note that most {@link Environment} implementations will include this system
-	 * a default {@link PropertySource} to be searched. Therefore, it is recommended that this method not be
+	 * environment map as a default {@link PropertySource} to be searched. Therefore, it
-	 * used directly unless bypassing other property sources is expressly intended.
+	 * 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};
+	 * <p>Calls to {@link Map#get(Object)} on the Map returned will never throw
-	 * in cases where the SecurityManager forbids access to a property, {@code null} will be returned and an
+	 * {@link IllegalAccessException}; in cases where the SecurityManager forbids access
-	 * INFO-level log message will be issued noting the exception.
+	 * to a property, {@code null} will be returned and an INFO-level log message will be
+	 * issued noting the exception.
 	 */
 	Map<String, Object> getSystemEnvironment();
 
 	/**
-	 * Return the value of {@link System#getProperties()} if allowed by the current {@link SecurityManager},
+	 * Return the value of {@link System#getProperties()} if allowed by the current
-	 * otherwise return a map implementation that will attempt to access individual keys using calls to
+	 * {@link SecurityManager}, otherwise return a map implementation that will attempt
-	 * {@link System#getProperty(String)}.
+	 * 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
+	 * <p>Note that most {@code Environment} implementations will include this system
-	 * default {@link PropertySource} to be searched. Therefore, it is recommended that this method not be
+	 * properties map as a default {@link PropertySource} to be searched. Therefore, it is
-	 * used directly unless bypassing other property sources is expressly intended.
+	 * 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};
+	 * <p>Calls to {@link Map#get(Object)} on the Map returned will never throw
-	 * in cases where the SecurityManager forbids access to a property, {@code null} will be returned and an
+	 * {@link IllegalAccessException}; in cases where the SecurityManager forbids access
-	 * INFO-level log message will be issued noting the exception.
+	 * to a property, {@code null} will be returned and an INFO-level log message will be
+	 * issued noting the exception.
 	 */
 	Map<String, Object> getSystemProperties();
 

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:
+ * Models two key aspects of the application environment: <em>profiles</em> and
- * <ol>
+ * <em>properties</em>.
- *   <li>profiles</li>
- *   <li>properties</li>
- * </ol>
  *
- * A <em>profile</em> is a named, logical group of bean definitions to be registered with the
+ * <p>A <em>profile</em> is a named, logical group of bean definitions to be registered
- * container only if the given profile is <em>active</em>. Beans may be assigned to a profile
+ * with the container only if the given profile is <em>active</em>. Beans may be assigned
- * whether defined in XML or annotations; see the spring-beans 3.1 schema or the {@link
+ * to a profile whether defined in XML or via annotations; see the spring-beans 3.1 schema
- * org.springframework.context.annotation.Profile @Profile} annotation for syntax details.
+ * or the {@link org.springframework.context.annotation.Profile @Profile} annotation for
- * The role of the Environment object with relation to profiles is in determining which profiles
+ * syntax details. The role of the {@code Environment} object with relation to profiles is
- * (if any) are currently {@linkplain #getActiveProfiles active}, and which profiles (if any)
+ * in determining which profiles (if any) are currently {@linkplain #getActiveProfiles
- * should be {@linkplain #getDefaultProfiles active by default}.
+ * active}, and which profiles (if any) should be {@linkplain #getDefaultProfiles active
+ * by default}.
  *
- * <p><em>Properties</em> play an important role in almost all applications, and may originate
+ * <p><em>Properties</em> play an important role in almost all applications, and may
- * from a variety of sources: properties files, JVM system properties, system environment
+ * originate from a variety of sources: properties files, JVM system properties, system
- * variables, JNDI, servlet context parameters, ad-hoc Properties objects, Maps, and so on.
+ * environment variables, JNDI, servlet context parameters, ad-hoc Properties objects,
- * The role of the environment object with relation to properties is to provide the user with a
+ * Maps, and so on. The role of the environment object with relation to properties is to
- * convenient service interface for configuring property sources and resolving properties from them.
+ * provide the user with a convenient service interface for configuring property sources
+ * and resolving properties from them.
  *
  * <p>Beans managed within an ApplicationContext may register to be {@link
- * org.springframework.context.EnvironmentAware EnvironmentAware}, where they can query profile state
+ * org.springframework.context.EnvironmentAware EnvironmentAware} or {@code @Inject} the
- * or resolve properties directly.
+ * {@code Environment} in order to query profile state or resolve properties directly.
  *
- * <p>More commonly, beans will not interact with the Environment directly, but will have ${...}
+ * <p>In most cases, however, application-level beans should not need to interact with the
- * property values replaced by a property placeholder configurer such as {@link
+ * {@code Environment} directly but instead may have to have <code>${...}</code> property
- * org.springframework.context.support.PropertySourcesPlaceholderConfigurer
+ * values replaced by a property placeholder configurer such as
- * PropertySourcesPlaceholderConfigurer}, which itself is EnvironmentAware, and as of Spring 3.1 is
+ * {@link org.springframework.context.support.PropertySourcesPlaceholderConfigurer
- * registered by default when using {@code <context:property-placeholder/>}.
+ * PropertySourcesPlaceholderConfigurer}, which itself is {@code EnvironmentAware} and
+ * as of Spring 3.1 is registered by default when using
+ * {@code <context:property-placeholder/>}.
  *
- * <p>Configuration of the environment object must be done through the {@link ConfigurableEnvironment}
+ * <p>Configuration of the environment object must be done through the
- * interface, returned from all AbstractApplicationContext subclass getEnvironment() methods. See
+ * {@link ConfigurableEnvironment} interface, returned from all
- * {@link DefaultEnvironment} for several examples of using the ConfigurableEnvironment interface
+ * {@code AbstractApplicationContext} subclass {@code getEnvironment()} methods. See
- * to manipulate property sources prior to application context refresh().
+ * {@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

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

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 {