From f60a40be44df5dc19059ddb635d1b40015b54de0 Mon Sep 17 00:00:00 2001 From: Chris Beams Date: Tue, 11 Oct 2011 18:51:26 +0000 Subject: [PATCH] Polish Environment subsystem Javadoc --- .../core/env/AbstractEnvironment.java | 8 ++++ .../core/env/ConfigurableEnvironment.java | 45 ++++++++++++++++++- .../env/ConfigurablePropertyResolver.java | 2 +- .../springframework/core/env/Environment.java | 11 ++--- .../core/env/StandardEnvironment.java | 35 ++------------- .../support/StandardServletEnvironment.java | 8 ++-- 6 files changed, 65 insertions(+), 44 deletions(-) diff --git a/org.springframework.core/src/main/java/org/springframework/core/env/AbstractEnvironment.java b/org.springframework.core/src/main/java/org/springframework/core/env/AbstractEnvironment.java index 5192c47e29..1fb99948f5 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/env/AbstractEnvironment.java +++ b/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. * + *

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 { 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 a49a5487a4..8e8aad80ea 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 @@ -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 - * as accessing underlying {@linkplain #getPropertySources() property sources}. + * 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 {@link ConfigurablePropertyResolver} + * superinterface. + * + *

Manipulating property sources

+ *

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

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 {@link Environment} is being used by an ApplicationContext, it is important + * that any such PropertySource manipulations be performed before 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 diff --git a/org.springframework.core/src/main/java/org/springframework/core/env/ConfigurablePropertyResolver.java b/org.springframework.core/src/main/java/org/springframework/core/env/ConfigurablePropertyResolver.java index 414a5a0038..ab5aa541dd 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/env/ConfigurablePropertyResolver.java +++ b/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. * 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 0a8ba0727b..792c1034d5 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 @@ -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: profiles and - * properties. + * properties. Methods related to property access are exposed via the + * {@link PropertyResolver} superinterface. * *

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

Beans managed within an ApplicationContext may register to be {@link + *

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

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 - * interface to manipulate property sources prior to application context refresh(). + * {@link ConfigurableEnvironment} Javadoc for usage examples demonstrating manipulation + * of property sources prior to application context {@code refresh()}. * * @author Chris Beams * @since 3.1 diff --git a/org.springframework.core/src/main/java/org/springframework/core/env/StandardEnvironment.java b/org.springframework.core/src/main/java/org/springframework/core/env/StandardEnvironment.java index 53915755fa..3d3344e394 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/env/StandardEnvironment.java +++ b/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; * *

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()}. - * - *

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 {@link Environment} is being used by an ApplicationContext, it is important - * that any such PropertySource manipulations be performed before 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}. + * instance available from {@link #getPropertySources()}. See + * {@link ConfigurableEnvironment} Javadoc for usage examples. * * @author Chris Beams * @since 3.1 diff --git a/org.springframework.web/src/main/java/org/springframework/web/context/support/StandardServletEnvironment.java b/org.springframework.web/src/main/java/org/springframework/web/context/support/StandardServletEnvironment.java index d2e7964e3e..c7bd56b815 100644 --- a/org.springframework.web/src/main/java/org/springframework/web/context/support/StandardServletEnvironment.java +++ b/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}. *

Properties in any of the above will take precedence over system properties and * environment variables contributed by the {@link StandardEnvironment} superclass. - *

The {@code Servlet}-related property sources are added as stubs for now, and - * will be {@linkplain WebApplicationContextUtils#initServletPropertySources fully - * initialized} once the actual {@link ServletConfig} and {@link ServletContext} - * objects are available. + *

The {@code Servlet}-related property sources are added as {@link + * StubPropertySource stubs} at this stage, and will be {@linkplain + * WebApplicationContextUtils#initServletPropertySources fully initialized} once the + * actual {@link ServletConfig} and {@link ServletContext} objects become available. * @see StandardEnvironment#customizePropertySources * @see org.springframework.core.env.AbstractEnvironment#customizePropertySources * @see ServletConfigPropertySource