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.

Author: cbeams

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

@@ -31,6 +31,12 @@
  * <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

spring-framework-reference/src/beans.xml

@@ -4149,7 +4149,13 @@ org.springframework.scripting.groovy.GroovyMessenger@272961</programlisting>
         <emphasis>instances</emphasis> (the objects that are created from the
         configuration metadata), then you instead need to use a
         <interfacename>BeanPostProcessor</interfacename> (described above in
-        <xref linkend="beans-factory-extension-bpp" />.</para>
+        <xref linkend="beans-factory-extension-bpp"/>.  While it is technically
+        possible to work with bean instances within a
+        <interfacename>BeanFactoryPostProcessor</interfacename> (e.g. using
+        <methodname>BeanFactory.getBean()</methodname>), doing so causes
+        premature bean instantiation, violating the usual containter lifecycle.
+        This may cause negative side effects such as bypassing bean post
+        processing.</para>
 
         <para>Also, <literal>BeanFactoryPostProcessors</literal> are scoped
         <emphasis>per-container</emphasis>. This is only relevant if you are