Clarify programmatic contract (no annotation-driven injection)

Issue: SPR-8704
(cherry picked from commit fd41f63)

Author: jhoeller

spring-beans/src/main/java/org/springframework/beans/factory/FactoryBean.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.
@@ -17,31 +17,34 @@
 package org.springframework.beans.factory;
 
 /**
- * Interface to be implemented by objects used within a {@link BeanFactory}
- * which are themselves factories. If a bean implements this interface,
- * it is used as a factory for an object to expose, not directly as a bean
- * instance that will be exposed itself.
+ * Interface to be implemented by objects used within a {@link BeanFactory} which
+ * are themselves factories for individual objects. If a bean implements this
+ * interface, it is used as a factory for an object to expose, not directly as a
+ * bean instance that will be exposed itself.
  *
- * <p><b>NB: A bean that implements this interface cannot be used as a
- * normal bean.</b> A FactoryBean is defined in a bean style, but the
- * object exposed for bean references ({@link #getObject()} is always
- * the object that it creates.
+ * <p><b>NB: A bean that implements this interface cannot be used as a normal bean.</b>
+ * A FactoryBean is defined in a bean style, but the object exposed for bean
+ * references ({@link #getObject()}) is always the object that it creates.
  *
- * <p>FactoryBeans can support singletons and prototypes, and can
- * either create objects lazily on demand or eagerly on startup.
- * The {@link SmartFactoryBean} interface allows for exposing
- * more fine-grained behavioral metadata.
+ * <p>FactoryBeans can support singletons and prototypes, and can either create
+ * objects lazily on demand or eagerly on startup. The {@link SmartFactoryBean}
+ * interface allows for exposing more fine-grained behavioral metadata.
  *
- * <p>This interface is heavily used within the framework itself, for
- * example for the AOP {@link org.springframework.aop.framework.ProxyFactoryBean}
- * or the {@link org.springframework.jndi.JndiObjectFactoryBean}.
- * It can be used for application components as well; however,
- * this is not common outside of infrastructure code.
+ * <p>This interface is heavily used within the framework itself, for example for
+ * the AOP {@link org.springframework.aop.framework.ProxyFactoryBean} or the
+ * {@link org.springframework.jndi.JndiObjectFactoryBean}. It can be used for
+ * custom components as well; however, this is only common for infrastructure code.
  *
- * <p><b>NOTE:</b> FactoryBean objects participate in the containing
- * BeanFactory's synchronization of bean creation. There is usually no
- * need for internal synchronization other than for purposes of lazy
- * initialization within the FactoryBean itself (or the like).
+ * <p><b>{@code FactoryBean} is a programmatic contract. Implementations are not
+ * supposed to rely on annotation-driven injection or other reflective facilities.</b>
+ * {@link #getObjectType()} {@link #getObject()} invocations may arrive early in
+ * the bootstrap process, even ahead of any post-processor setup. If you need access
+ * other beans, implement {@link BeanFactoryAware} and obtain them programmatically.
+ *
+ * <p>Finally, FactoryBean objects participate in the containing BeanFactory's
+ * synchronization of bean creation. There is usually no need for internal
+ * synchronization other than for purposes of lazy initialization within the
+ * FactoryBean itself (or the like).
  *
  * @author Rod Johnson
  * @author Juergen Hoeller