root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Polish Environment subsystem Javadoc

This commit is contained in:
Chris Beams 2011-10-11 18:51:26 +00:00
parent 3920c5a158
commit f60a40be44
6 changed files with 65 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
org.springframework.core/src/main/java/org/springframework/core/env/AbstractEnvironment.java vendored
View File

@ -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 {

45
org.springframework.core/src/main/java/org/springframework/core/env/ConfigurableEnvironment.java vendored
View File

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

2
org.springframework.core/src/main/java/org/springframework/core/env/ConfigurablePropertyResolver.java vendored
View File

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

11
org.springframework.core/src/main/java/org/springframework/core/env/Environment.java vendored
View File

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

35
org.springframework.core/src/main/java/org/springframework/core/env/StandardEnvironment.java vendored
View File

@ -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()}.
*
* <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}.
* instance available from {@link #getPropertySources()}. See
* {@link ConfigurableEnvironment} Javadoc for usage examples.
*
* @author Chris Beams
* @since 3.1

8
org.springframework.web/src/main/java/org/springframework/web/context/support/StandardServletEnvironment.java
View File

@ -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
* will be {@linkplain WebApplicationContextUtils#initServletPropertySources fully
* initialized} once the actual {@link ServletConfig} and {@link ServletContext}
* objects are available.
* <p>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