Polishing

(cherry picked from commit 154ef8b)

spring-beans/src/main/java/org/springframework/beans/factory/support/BeanDefinitionReaderUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -69,6 +69,23 @@ public class BeanDefinitionReaderUtils {
 		return bd;
 	}
 
+	/**
+	 * Generate a bean name for the given top-level bean definition,
+	 * unique within the given bean factory.
+	 * @param beanDefinition the bean definition to generate a bean name for
+	 * @param registry the bean factory that the definition is going to be
+	 * registered with (to check for existing bean names)
+	 * @return the generated bean name
+	 * @throws BeanDefinitionStoreException if no unique name can be generated
+	 * for the given bean definition
+	 * @see #generateBeanName(BeanDefinition, BeanDefinitionRegistry, boolean)
+	 */
+	public static String generateBeanName(BeanDefinition beanDefinition, BeanDefinitionRegistry registry)
+			throws BeanDefinitionStoreException {
+
+		return generateBeanName(beanDefinition, registry, false);
+	}
+
 	/**
 	 * Generate a bean name for the given bean definition, unique within the
 	 * given bean factory.
@@ -117,22 +134,6 @@ public class BeanDefinitionReaderUtils {
 		return id;
 	}
 
-	/**
-	 * Generate a bean name for the given top-level bean definition,
-	 * unique within the given bean factory.
-	 * @param beanDefinition the bean definition to generate a bean name for
-	 * @param registry the bean factory that the definition is going to be
-	 * registered with (to check for existing bean names)
-	 * @return the generated bean name
-	 * @throws BeanDefinitionStoreException if no unique name can be generated
-	 * for the given bean definition
-	 */
-	public static String generateBeanName(BeanDefinition beanDefinition, BeanDefinitionRegistry registry)
-			throws BeanDefinitionStoreException {
-
-		return generateBeanName(beanDefinition, registry, false);
-	}
-
 	/**
 	 * Register the given bean definition with the given bean factory.
 	 * @param definitionHolder the bean definition including name and aliases

spring-context/src/main/java/org/springframework/context/ConfigurableApplicationContext.java

@@ -54,6 +54,7 @@ public interface ConfigurableApplicationContext extends ApplicationContext, Life
 	 * Name of the ConversionService bean in the factory.
 	 * If none is supplied, default conversion rules apply.
 	 * @see org.springframework.core.convert.ConversionService
+	 * @since 3.0
 	 */
 	String CONVERSION_SERVICE_BEAN_NAME = "conversionService";
 
@@ -61,12 +62,14 @@ public interface ConfigurableApplicationContext extends ApplicationContext, Life
 	 * Name of the LoadTimeWeaver bean in the factory. If such a bean is supplied,
 	 * the context will use a temporary ClassLoader for type matching, in order
 	 * to allow the LoadTimeWeaver to process all actual bean classes.
+	 * @since 2.5
 	 * @see org.springframework.instrument.classloading.LoadTimeWeaver
 	 */
 	String LOAD_TIME_WEAVER_BEAN_NAME = "loadTimeWeaver";
 
 	/**
 	 * Name of the {@link Environment} bean in the factory.
+	 * @since 3.1
 	 */
 	String ENVIRONMENT_BEAN_NAME = "environment";
 
@@ -85,6 +88,7 @@ public interface ConfigurableApplicationContext extends ApplicationContext, Life
 
 	/**
 	 * Set the unique id of this application context.
+	 * @since 3.0
 	 */
 	void setId(String id);
 
@@ -100,6 +104,7 @@ public interface ConfigurableApplicationContext extends ApplicationContext, Life
 
 	/**
 	 * Return the Environment for this application context in configurable form.
+	 * @since 3.1
 	 */
 	@Override
 	ConfigurableEnvironment getEnvironment();
@@ -107,6 +112,7 @@ public interface ConfigurableApplicationContext extends ApplicationContext, Life
 	/**
 	 * Set the {@code Environment} for this application context.
 	 * @param environment the new environment
+	 * @since 3.1
 	 */
 	void setEnvironment(ConfigurableEnvironment environment);
 

spring-context/src/main/java/org/springframework/context/annotation/AnnotatedBeanDefinitionReader.java

@@ -83,6 +83,7 @@ public class AnnotatedBeanDefinitionReader {
 		AnnotationConfigUtils.registerAnnotationConfigProcessors(this.registry);
 	}
 
+
 	/**
 	 * Return the BeanDefinitionRegistry that this scanner operates on.
 	 */
@@ -117,21 +118,50 @@ public class AnnotatedBeanDefinitionReader {
 				(scopeMetadataResolver != null ? scopeMetadataResolver : new AnnotationScopeMetadataResolver());
 	}
 
+
+	/**
+	 * Register one or more annotated classes to be processed.
+	 * <p>Calls to {@code register} are idempotent; adding the same
+	 * annotated class more than once has no additional effect.
+	 * @param annotatedClasses one or more annotated classes,
+	 * e.g. {@link Configuration @Configuration} classes
+	 */
 	public void register(Class<?>... annotatedClasses) {
 		for (Class<?> annotatedClass : annotatedClasses) {
 			registerBean(annotatedClass);
 		}
 	}
 
+	/**
+	 * Register a bean from the given bean class, deriving its metadata from
+	 * class-declared annotations.
+	 * @param annotatedClass the class of the bean
+	 */
+	@SuppressWarnings("unchecked")
 	public void registerBean(Class<?> annotatedClass) {
 		registerBean(annotatedClass, null, (Class<? extends Annotation>[]) null);
 	}
 
+	/**
+	 * Register a bean from the given bean class, deriving its metadata from
+	 * class-declared annotations.
+	 * @param annotatedClass the class of the bean
+	 * @param qualifiers specific qualifier annotations to consider,
+	 * in addition to qualifiers at the bean class level
+	 */
 	@SuppressWarnings("unchecked")
 	public void registerBean(Class<?> annotatedClass, Class<? extends Annotation>... qualifiers) {
 		registerBean(annotatedClass, null, qualifiers);
 	}
 
+	/**
+	 * Register a bean from the given bean class, deriving its metadata from
+	 * class-declared annotations.
+	 * @param annotatedClass the class of the bean
+	 * @param name an explicit name for the bean
+	 * @param qualifiers specific qualifier annotations to consider,
+	 * in addition to qualifiers at the bean class level
+	 */
 	@SuppressWarnings("unchecked")
 	public void registerBean(Class<?> annotatedClass, String name, Class<? extends Annotation>... qualifiers) {
 		AnnotatedGenericBeanDefinition abd = new AnnotatedGenericBeanDefinition(annotatedClass);

spring-context/src/main/java/org/springframework/context/annotation/AnnotationConfigApplicationContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -135,6 +135,16 @@ public class AnnotationConfigApplicationContext extends GenericApplicationContex
 		this.scanner.setScopeMetadataResolver(scopeMetadataResolver);
 	}
 
+	@Override
+	protected void prepareRefresh() {
+		this.scanner.clearCache();
+		super.prepareRefresh();
+	}
+
+
+	//---------------------------------------------------------------------
+	// Implementation of AnnotationConfigRegistry
+	//---------------------------------------------------------------------
 
 	/**
 	 * Register one or more annotated classes to be processed.
@@ -163,11 +173,4 @@ public class AnnotationConfigApplicationContext extends GenericApplicationContex
 		this.scanner.scan(basePackages);
 	}
 
-
-	@Override
-	protected void prepareRefresh() {
-		this.scanner.clearCache();
-		super.prepareRefresh();
-	}
-
 }

spring-context/src/main/java/org/springframework/context/support/GenericApplicationContext.java

@@ -160,6 +160,7 @@ public class GenericApplicationContext extends AbstractApplicationContext implem
 	 * Set whether it should be allowed to override bean definitions by registering
 	 * a different definition with the same name, automatically replacing the former.
 	 * If not, an exception will be thrown. Default is "true".
+	 * @since 3.0
 	 * @see org.springframework.beans.factory.support.DefaultListableBeanFactory#setAllowBeanDefinitionOverriding
 	 */
 	public void setAllowBeanDefinitionOverriding(boolean allowBeanDefinitionOverriding) {
@@ -171,6 +172,7 @@ public class GenericApplicationContext extends AbstractApplicationContext implem
 	 * try to resolve them.
 	 * <p>Default is "true". Turn this off to throw an exception when encountering
 	 * a circular reference, disallowing them completely.
+	 * @since 3.0
 	 * @see org.springframework.beans.factory.support.DefaultListableBeanFactory#setAllowCircularReferences
 	 */
 	public void setAllowCircularReferences(boolean allowCircularReferences) {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -35,24 +35,24 @@ import java.util.Map;
  *
  * <h4>Example: adding a new property source with highest search priority</h4>
  * <pre class="code">
- *   ConfigurableEnvironment environment = new StandardEnvironment();
+ * ConfigurableEnvironment environment = new StandardEnvironment();
- *   MutablePropertySources propertySources = environment.getPropertySources();
+ * MutablePropertySources propertySources = environment.getPropertySources();
- *   Map<String, String> myMap = new HashMap<String, String>();
+ * Map<String, String> myMap = new HashMap<String, String>();
- *   myMap.put("xyz", "myValue");
+ * myMap.put("xyz", "myValue");
- *   propertySources.addFirst(new MapPropertySource("MY_MAP", myMap));
+ * 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();
+ * MutablePropertySources propertySources = environment.getPropertySources();
- *   propertySources.remove(StandardEnvironment.SYSTEM_PROPERTIES_PROPERTY_SOURCE_NAME)
+ * 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();
+ * MutablePropertySources propertySources = environment.getPropertySources();
- *   MockPropertySource mockEnvVars = new MockPropertySource().withProperty("xyz", "myValue");
+ * MockPropertySource mockEnvVars = new MockPropertySource().withProperty("xyz", "myValue");
- *   propertySources.replace(StandardEnvironment.SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME, mockEnvVars);
+ * propertySources.replace(StandardEnvironment.SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME, mockEnvVars);
  * </pre>
  *
  * When an {@link Environment} is being used by an {@code ApplicationContext}, it is
@@ -64,7 +64,6 @@ import java.util.Map;
  * org.springframework.context.support.PropertySourcesPlaceholderConfigurer property
  * placeholder configurers}.
  *
- *
  * @author Chris Beams
  * @since 3.1
  * @see StandardEnvironment

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -77,8 +77,8 @@ public interface Environment extends PropertyResolver {
 	 * activated by setting {@linkplain AbstractEnvironment#ACTIVE_PROFILES_PROPERTY_NAME
 	 * "spring.profiles.active"} as a system property or by calling
 	 * {@link ConfigurableEnvironment#setActiveProfiles(String...)}.
-	 * <p>If no profiles have explicitly been specified as active, then any {@linkplain
+	 * <p>If no profiles have explicitly been specified as active, then any
-	 * #getDefaultProfiles() default profiles} will automatically be activated.
+	 * {@linkplain #getDefaultProfiles() default profiles} will automatically be activated.
 	 * @see #getDefaultProfiles
 	 * @see ConfigurableEnvironment#setActiveProfiles
 	 * @see AbstractEnvironment#ACTIVE_PROFILES_PROPERTY_NAME