From 2a896753d46e8031d91b21c04ce0d4700dbf0745 Mon Sep 17 00:00:00 2001 From: Chris Beams Date: Wed, 25 May 2011 10:52:03 +0000 Subject: [PATCH] Polish PropertySource and Environment Javadoc git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@4363 50f2f4bb-b051-0410-bef5-90022cba6387 --- .../context/annotation/Configuration.java | 3 +- .../context/annotation/PropertySource.java | 21 +++++++------ .../core/env/PropertySource.java | 30 ++++++++++++------- .../core/env/StandardEnvironment.java | 3 +- .../context/StandardPortletEnvironment.java | 1 + .../support/StandardServletEnvironment.java | 1 + 6 files changed, 37 insertions(+), 22 deletions(-) diff --git a/org.springframework.context/src/main/java/org/springframework/context/annotation/Configuration.java b/org.springframework.context/src/main/java/org/springframework/context/annotation/Configuration.java index 58091101fad..ae6d2e5dfc0 100644 --- a/org.springframework.context/src/main/java/org/springframework/context/annotation/Configuration.java +++ b/org.springframework.context/src/main/java/org/springframework/context/annotation/Configuration.java @@ -98,7 +98,8 @@ import org.springframework.stereotype.Component; *

Using the {@code Environment} API

* Externalized values may be looked up by injecting the Spring * {@link org.springframework.core.env.Environment Environment} into a - * {@code @Configuration} class: + * {@code @Configuration} class using the {@code @Autowired} or the {@code @Inject} + * annotation: * 
  * @Configuration
  * public class AppConfig {
diff --git a/org.springframework.context/src/main/java/org/springframework/context/annotation/PropertySource.java b/org.springframework.context/src/main/java/org/springframework/context/annotation/PropertySource.java
index d41e0b46452..4cb749d766e 100644
--- a/org.springframework.context/src/main/java/org/springframework/context/annotation/PropertySource.java
+++ b/org.springframework.context/src/main/java/org/springframework/context/annotation/PropertySource.java
@@ -49,10 +49,10 @@ import java.lang.annotation.Target;
  *     }
  * }
* - * Notice that the {@code Environment} object is @{@link Autowired} into the - * configuration class and then used when populating the {@code TestBean} - * object. Given the configuration above, a call to {@code testBean.getName()} will - * return "myTestBean". + * Notice that the {@code Environment} object is @{@link + * org.springframework.beans.factory.annotation.Autowired Autowired} into the + * configuration class and then used when populating the {@code TestBean} object. Given + * the configuration above, a call to {@code testBean.getName()} will return "myTestBean". * *

A note on property overriding with @PropertySource

* In cases where a given property key exists in more than one {@code .properties} @@ -91,13 +91,16 @@ import java.lang.annotation.Target; * if the {@code @Configuration} classes above were registered via component-scanning, * the ordering is difficult to predict. In such cases - and if overriding is important - * it is recommended that the user fall back to using the programmatic PropertySource API. - * See {@link org.springframework.core.env.ConfigurableEnvironment ConfigurableEnvironment} and - * {@link org.springframework.core.env.MutablePropertySources MutablePropertySources} Javadoc - * for details. - + * See {@link org.springframework.core.env.ConfigurableEnvironment ConfigurableEnvironment} + * and * {@link org.springframework.core.env.MutablePropertySources MutablePropertySources} + * Javadoc for details. * * @author Chris Beams * @since 3.1 + * @see Configuration + * @see org.springframework.core.env.PropertySource + * @see org.springframework.core.env.ConfigurableEnvironment#getPropertySources() + * @see org.springframework.core.env.MutablePropertySources */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @@ -105,7 +108,7 @@ import java.lang.annotation.Target; public @interface PropertySource { /** - * Indicate the name of this PropertySource. If omitted, a name + * Indicate the name of this property source. If omitted, a name * will be generated based on the description of the underlying * resource. * @see org.springframework.core.env.PropertySource#getName() diff --git a/org.springframework.core/src/main/java/org/springframework/core/env/PropertySource.java b/org.springframework.core/src/main/java/org/springframework/core/env/PropertySource.java index 9a12ae49a5f..3a028fe7587 100644 --- a/org.springframework.core/src/main/java/org/springframework/core/env/PropertySource.java +++ b/org.springframework.core/src/main/java/org/springframework/core/env/PropertySource.java @@ -24,19 +24,26 @@ import org.springframework.util.Assert; * Abstract base class representing a source of key/value property pairs. The underlying * {@linkplain #getSource() source object} may be of any type {@code T} that encapsulates * properties. Examples include {@link java.util.Properties} objects, {@link java.util.Map} - * objects, {@code ServletContext} and {@code ServletConfig} objects (for access to init parameters). - * Explore the {@code PropertySource} type hierarchy to see provided implementations. + * objects, {@code ServletContext} and {@code ServletConfig} objects (for access to init + * parameters). Explore the {@code PropertySource} type hierarchy to see provided + * implementations. * - *

{@code PropertySource} objects are not typically used in isolation, but rather through a - * {@link PropertySources} object, which aggregates property sources and in conjunction with - * a {@link PropertyResolver} implementation that can perform precedence-based searches across - * the set of {@code PropertySources}. + *

{@code PropertySource} objects are not typically used in isolation, but rather + * through a {@link PropertySources} object, which aggregates property sources and in + * conjunction with a {@link PropertyResolver} implementation that can perform + * precedence-based searches across the set of {@code PropertySources}. * - *

{@code PropertySource} identity is determined not based on the content of encapsulated - * properties, but rather based on the {@link #getName() name} of the {@code PropertySource} - * alone. This is useful for manipulating {@code PropertySource} objects when in collection - * contexts. See operations in {@link MutablePropertySources} as well as the - * {@link #named(String)} and {@link #toString()} methods for details. + *

{@code PropertySource} identity is determined not based on the content of + * encapsulated properties, but rather based on the {@link #getName() name} of the + * {@code PropertySource} alone. This is useful for manipulating {@code PropertySource} + * objects when in collection contexts. See operations in {@link MutablePropertySources} + * as well as the {@link #named(String)} and {@link #toString()} methods for details. + * + *

Note that when working with @{@link + * org.springframework.context.annotation.Configuration Configuration} classes that + * the @{@link org.springframework.context.annotation.PropertySource PropertySource} + * annotation provides a convenient and declarative way of adding property sources to the + * enclosing {@code Environment}. * * @author Chris Beams * @since 3.1 @@ -44,6 +51,7 @@ import org.springframework.util.Assert; * @see PropertyResolver * @see PropertySourcesPropertyResolver * @see MutablePropertySources + * @see org.springframework.context.annotation.PropertySource */ public abstract class PropertySource { 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 f4bd038102a..53915755fa6 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 @@ -67,7 +67,7 @@ package org.springframework.core.env; * {@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 - * {@link org.springframework.context.support.PropertySourcesPlaceholderConfigurer + * {@linkplain org.springframework.context.support.PropertySourcesPlaceholderConfigurer * property placeholder configurers}. * * @author Chris Beams @@ -93,6 +93,7 @@ public class StandardEnvironment extends AbstractEnvironment { * *

Properties present in {@value #SYSTEM_PROPERTIES_PROPERTY_SOURCE_NAME} will * take precedence over those in {@value #SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME}. + * @see AbstractEnvironment#customizePropertySources(MutablePropertySources) * @see #getSystemProperties() * @see #getSystemEnvironment() */ diff --git a/org.springframework.web.portlet/src/main/java/org/springframework/web/portlet/context/StandardPortletEnvironment.java b/org.springframework.web.portlet/src/main/java/org/springframework/web/portlet/context/StandardPortletEnvironment.java index c4f241bc113..a30bf09c685 100644 --- a/org.springframework.web.portlet/src/main/java/org/springframework/web/portlet/context/StandardPortletEnvironment.java +++ b/org.springframework.web.portlet/src/main/java/org/springframework/web/portlet/context/StandardPortletEnvironment.java @@ -68,6 +68,7 @@ public class StandardPortletEnvironment extends StandardEnvironment { * initialized} once the actual {@link PortletConfig}, {@link PortletContext}, and * {@link ServletContext} objects are available. * @see StandardEnvironment#customizePropertySources + * @see org.springframework.core.env.AbstractEnvironment#customizePropertySources * @see PortletConfigPropertySource * @see PortletContextPropertySource * @see AbstractRefreshablePortletApplicationContext#initPropertySources 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 c23d62ec237..534c728af63 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 @@ -77,6 +77,7 @@ public class StandardServletEnvironment extends StandardEnvironment { * servlet property sources, but higher than system properties and environment * variables. * @see StandardEnvironment#customizePropertySources + * @see org.springframework.core.env.AbstractEnvironment#customizePropertySources * @see ServletConfigPropertySource * @see ServletContextPropertySource * @see org.springframework.jndi.JndiPropertySource