DisposableBean javadoc refers to singletons as well as scoped beans

Issue: SPR-17131

(cherry picked from commit f155d21)

Author: jhoeller

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 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,27 +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 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-2012 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,31 +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 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-2015 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,16 +30,16 @@
 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;