DisposableBean javadoc refers to singletons as well as scoped beans

Issue: SPR-17131

(cherry picked from commit f155d21c95)

spring-beans/src/main/java/org/springframework/beans/factory/DisposableBean.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -17,28 +17,29 @@
 package org.springframework.beans.factory;
 
 /**
- * Interface to be implemented by beans that want to release resources
- * on destruction. A BeanFactory is supposed to invoke the destroy
- * method if it disposes a cached singleton. An application context
- * is supposed to dispose all of its singletons on close.
+ * Interface to be implemented by beans that want to release resources on destruction.
+ * A {@link BeanFactory} will invoke the destroy method on individual destruction of a
+ * scoped bean. An {@link org.springframework.context.ApplicationContext} is supposed
+ * to dispose all of its singletons on shutdown, driven by the application lifecycle.
  *
- * <p>An alternative to implementing DisposableBean is specifying a custom
- * destroy-method, for example in an XML bean definition.
- * For a list of all bean lifecycle methods, see the
- * {@link BeanFactory BeanFactory javadocs}.
+ * <p>A Spring-managed bean may also implement Java's {@link AutoCloseable} interface
+ * for the same purpose. An alternative to implementing an interface is specifying a
+ * custom destroy method, for example in an XML bean definition. For a list of all
+ * bean lifecycle methods, see the {@link BeanFactory BeanFactory javadocs}.
  *
  * @author Juergen Hoeller
  * @since 12.08.2003
- * @see org.springframework.beans.factory.support.RootBeanDefinition#getDestroyMethodName
- * @see org.springframework.context.ConfigurableApplicationContext#close
+ * @see InitializingBean
+ * @see org.springframework.beans.factory.support.RootBeanDefinition#getDestroyMethodName()
+ * @see org.springframework.beans.factory.config.ConfigurableBeanFactory#destroySingletons()
+ * @see org.springframework.context.ConfigurableApplicationContext#close()
  */
 public interface DisposableBean {
 
 	/**
-	 * Invoked by a BeanFactory on destruction of a singleton.
-	 * @throws Exception in case of shutdown errors.
-	 * Exceptions will get logged but not rethrown to allow
-	 * other beans to release their resources too.
+	 * Invoked by the containing {@code BeanFactory} on destruction of a bean.
+	 * @throws Exception in case of shutdown errors. Exceptions will get logged
+	 * but not rethrown to allow other beans to release their resources as well.
 	 */
 	void destroy() throws Exception;
 

spring-beans/src/main/java/org/springframework/beans/factory/InitializingBean.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -17,32 +17,29 @@
 package org.springframework.beans.factory;
 
 /**
- * Interface to be implemented by beans that need to react once all their
- * properties have been set by a BeanFactory: for example, to perform custom
- * initialization, or merely to check that all mandatory properties have been set.
+ * Interface to be implemented by beans that need to react once all their properties
+ * have been set by a {@link BeanFactory}: e.g. to perform custom initialization,
+ * or merely to check that all mandatory properties have been set.
  *
- * <p>An alternative to implementing InitializingBean is specifying a custom
- * init-method, for example in an XML bean definition.
- * For a list of all bean lifecycle methods, see the
- * {@link BeanFactory BeanFactory javadocs}.
+ * <p>An alternative to implementing {@code InitializingBean} is specifying a custom
+ * init method, for example in an XML bean definition. For a list of all bean
+ * lifecycle methods, see the {@link BeanFactory BeanFactory javadocs}.
  *
  * @author Rod Johnson
- * @see BeanNameAware
- * @see BeanFactoryAware
- * @see BeanFactory
- * @see org.springframework.beans.factory.support.RootBeanDefinition#getInitMethodName
- * @see org.springframework.context.ApplicationContextAware
+ * @author Juergen Hoeller
+ * @see DisposableBean
+ * @see org.springframework.beans.factory.config.BeanDefinition#getPropertyValues()
+ * @see org.springframework.beans.factory.support.AbstractBeanDefinition#getInitMethodName()
  */
 public interface InitializingBean {
 
 	/**
-	 * Invoked by a BeanFactory after it has set all bean properties supplied
-	 * (and satisfied BeanFactoryAware and ApplicationContextAware).
-	 * <p>This method allows the bean instance to perform initialization only
-	 * possible when all bean properties have been set and to throw an
-	 * exception in the event of misconfiguration.
-	 * @throws Exception in the event of misconfiguration (such
-	 * as failure to set an essential property) or if initialization fails.
+	 * Invoked by the containing {@code BeanFactory} after it has set all bean properties
+	 * and satisfied {@link BeanFactoryAware}, {@code ApplicationContextAware} etc.
+	 * <p>This method allows the bean instance to perform validation of its overall
+	 * configuration and final initialization when all bean properties have been set.
+	 * @throws Exception in the event of misconfiguration (such as failure to set an
+	 * essential property) or if initialization fails for any other reason
 	 */
 	void afterPropertiesSet() throws Exception;
 

spring-beans/src/main/java/org/springframework/beans/factory/config/DestructionAwareBeanPostProcessor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -30,32 +30,25 @@ import org.springframework.beans.BeansException;
 public interface DestructionAwareBeanPostProcessor extends BeanPostProcessor {
 
 	/**
-	 * Apply this BeanPostProcessor to the given bean instance before
-	 * its destruction. Can invoke custom destruction callbacks.
-	 * <p>Like DisposableBean's {@code destroy} and a custom destroy method,
-	 * this callback just applies to singleton beans in the factory (including
-	 * inner beans).
+	 * Apply this BeanPostProcessor to the given bean instance before its
+	 * destruction, e.g. invoking custom destruction callbacks.
+	 * <p>Like DisposableBean's {@code destroy} and a custom destroy method, this
+	 * callback will only apply to beans which the container fully manages the
+	 * lifecycle for. This is usually the case for singletons and scoped beans.
 	 * @param bean the bean instance to be destroyed
 	 * @param beanName the name of the bean
 	 * @throws org.springframework.beans.BeansException in case of errors
-	 * @see org.springframework.beans.factory.DisposableBean
-	 * @see org.springframework.beans.factory.support.AbstractBeanDefinition#setDestroyMethodName
+	 * @see org.springframework.beans.factory.DisposableBean#destroy()
+	 * @see org.springframework.beans.factory.support.AbstractBeanDefinition#setDestroyMethodName(String)
 	 */
 	void postProcessBeforeDestruction(Object bean, String beanName) throws BeansException;
 
 	/**
 	 * Determine whether the given bean instance requires destruction by this
 	 * post-processor.
-	 * <p><b>NOTE:</b> Even as a late addition, this method has been introduced on
-	 * {@code DestructionAwareBeanPostProcessor} itself instead of on a SmartDABPP
-	 * subinterface. This allows existing {@code DestructionAwareBeanPostProcessor}
-	 * implementations to easily provide {@code requiresDestruction} logic while
-	 * retaining compatibility with Spring <4.3, and it is also an easier onramp to
-	 * declaring {@code requiresDestruction} as a Java 8 default method in Spring 5.
-	 * <p>If an implementation of {@code DestructionAwareBeanPostProcessor} does
-	 * not provide a concrete implementation of this method, Spring's invocation
-	 * mechanism silently assumes a method returning {@code true} (the effective
-	 * default before 4.3, and the to-be-default in the Java 8 method in Spring 5).
+	 * <p>The default implementation returns {@code true}. If a pre-5 implementation
+	 * of {@code DestructionAwareBeanPostProcessor} does not provide a concrete
+	 * implementation of this method, Spring silently assumes {@code true} as well.
 	 * @param bean the bean instance to check
 	 * @return {@code true} if {@link #postProcessBeforeDestruction} is supposed to
 	 * be called for this bean instance eventually, or {@code false} if not needed