Polish Environment subsystem Javadoc

org.springframework.core/src/main/java/org/springframework/core/env/AbstractEnvironment.java

@@ -38,8 +38,16 @@ import org.springframework.util.StringUtils;
  * through the {@link #ACTIVE_PROFILES_PROPERTY_NAME} and
  * {@link #DEFAULT_PROFILES_PROPERTY_NAME} properties.
  *
+ * <p>Concrete subclasses differ primarily on which {@link PropertySource} objects they
+ * add by default. {@code AbstractEnvironment} adds none. Subclasses should contribute
+ * property sources through the protected {@link #customizePropertySources()} hook, while
+ * clients should customize using {@link ConfigurableEnvironment#getPropertySources()} and
+ * working against the {@link MutablePropertySources} API. See
+ * {@link ConfigurableEnvironment} Javadoc for usage examples.
+ *
  * @author Chris Beams
  * @since 3.1
+ * @see ConfigurableEnvironment
  * @see StandardEnvironment
  */
 public abstract class AbstractEnvironment implements ConfigurableEnvironment {

org.springframework.core/src/main/java/org/springframework/core/env/ConfigurableEnvironment.java

@@ -20,8 +20,49 @@ import java.util.Map;
 
 /**
  * Configuration interface to be implemented by most if not all {@link Environment} types.
- * Provides facilities for setting active and default profiles as well
+ * Provides facilities for setting active and default profiles and manipulating underlying
- * as accessing underlying {@linkplain #getPropertySources() property sources}.
+ * 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<String, String>();
+ *   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 ApplicationContext, it is important
+ * that any such 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

org.springframework.core/src/main/java/org/springframework/core/env/ConfigurablePropertyResolver.java

@@ -20,7 +20,7 @@ import org.springframework.core.convert.support.ConfigurableConversionService;
 
 /**
  * Configuration interface to be implemented by most if not all {@link PropertyResolver
- * PropertyResolvers}. Provides facilities for accessing and customizing the
+ * PropertyResolver} types. Provides facilities for accessing and customizing the
  * {@link org.springframework.core.convert.ConversionService ConversionService} used when
  * converting property values from one type to another.
  *

org.springframework.core/src/main/java/org/springframework/core/env/Environment.java

@@ -19,7 +19,8 @@ package org.springframework.core.env;
 /**
  * Interface representing the environment in which the current application is running.
  * Models two key aspects of the application environment: <em>profiles</em> and
- * <em>properties</em>.
+ * <em>properties</em>. Methods related to property access are exposed via the
+ * {@link PropertyResolver} superinterface.
  *
  * <p>A <em>profile</em> is a named, logical group of bean definitions to be registered
  * with the container only if the given profile is <em>active</em>. Beans may be assigned
@@ -37,7 +38,7 @@ package org.springframework.core.env;
  * 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
+ * <p>Beans managed within an {@code ApplicationContext} may register to be {@link
  * org.springframework.context.EnvironmentAware EnvironmentAware} or {@code @Inject} the
  * {@code Environment} in order to query profile state or resolve properties directly.
  *
@@ -50,10 +51,10 @@ package org.springframework.core.env;
  * {@code <context:property-placeholder/>}.
  *
  * <p>Configuration of the environment object must be done through the
- * {@link ConfigurableEnvironment} interface, returned from all
+ * {@code ConfigurableEnvironment} interface, returned from all
  * {@code AbstractApplicationContext} subclass {@code getEnvironment()} methods. See
- * {@link StandardEnvironment} for several examples of using the ConfigurableEnvironment
+ * {@link ConfigurableEnvironment} Javadoc for usage examples demonstrating manipulation
- * interface to manipulate property sources prior to application context refresh().
+ * of property sources prior to application context {@code refresh()}.
  *
  * @author Chris Beams
  * @since 3.1

org.springframework.core/src/main/java/org/springframework/core/env/StandardEnvironment.java

@@ -30,7 +30,7 @@ package org.springframework.core.env;
  *
  * That is, if the key "xyz" is present both in the JVM system properties as well as in
  * the set of environment variables for the current process, the value of key "xyz" from
- * system properties * will return from a call to {@code environment.getProperty("xyz")}.
+ * system properties will return from a call to {@code environment.getProperty("xyz")}.
  * This ordering is chosen by default because system properties are per-JVM, while
  * environment variables may be the same across many JVMs on a given system.  Giving
  * system properties precedence allows for overriding of environment variables on a
@@ -38,37 +38,8 @@ package org.springframework.core.env;
  *
  * <p>These default property sources may be removed, reordered, or replaced; and
  * additional property sources may be added using the {@link MutablePropertySources}
- * instance available from {@link #getPropertySources()}.
+ * instance available from {@link #getPropertySources()}. See
- *
+ * {@link ConfigurableEnvironment} Javadoc for usage examples.
- * <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<String, String>();
- *   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 ApplicationContext, it is important
- * that any such 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 PropertySources 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

org.springframework.web/src/main/java/org/springframework/web/context/support/StandardServletEnvironment.java

@@ -65,10 +65,10 @@ public class StandardServletEnvironment extends StandardEnvironment {
 	 * {@value #JNDI_PROPERTY_SOURCE_NAME}.
 	 * <p>Properties in any of the above will take precedence over system properties and
 	 * environment variables contributed by the {@link StandardEnvironment} superclass.
-	 * <p>The {@code Servlet}-related property sources are added as stubs for now, and
+	 * <p>The {@code Servlet}-related property sources are added as {@link
-	 * will be {@linkplain WebApplicationContextUtils#initServletPropertySources fully
+	 * StubPropertySource stubs} at this stage, and will be {@linkplain
-	 * initialized} once the actual {@link ServletConfig} and {@link ServletContext}
+	 * WebApplicationContextUtils#initServletPropertySources fully initialized} once the
-	 * objects are available.
+	 * actual {@link ServletConfig} and {@link ServletContext} objects become available.
 	 * @see StandardEnvironment#customizePropertySources
 	 * @see org.springframework.core.env.AbstractEnvironment#customizePropertySources
 	 * @see ServletConfigPropertySource