Document BeanFactoryPostProcessor implementation constraints (SPR-7466)

JavaDoc and reference docs now warn developers against interacting with
bean instances within BeanFactoryPostProcessor implementations in order
to avoid premature bean instantiation.

See SPR-7450 for an example of a third-party BFPP
(OAuthTokenLifecycleRegistryPostProcessor) prematurely instantiating
a FactoryBean instance, such that bean post-processing is bypassed
and autowired injection (via @Inject) never occurs.

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@3602 50f2f4bb-b051-0410-bef5-90022cba6387

org.springframework.beans/src/main/java/org/springframework/beans/factory/config/BeanFactoryPostProcessor.java

@@ -31,6 +31,12 @@ import org.springframework.beans.BeansException;
  * <p>See PropertyResourceConfigurer and its concrete implementations
  * for out-of-the-box solutions that address such configuration needs.
  *
+ * <p>A BeanFactoryPostProcessor may interact with and modify bean
+ * definitions, but never bean instances. Doing so may cause premature bean
+ * instantiation, violating the container and causing unintended side-effects.
+ * If bean instance interaction is required, consider implementing
+ * {@link BeanPostProcessor} instead.
+ *
  * @author Juergen Hoeller
  * @since 06.07.2003
  * @see BeanPostProcessor