Document @Autowired and @value limitations

@Autowired, @value and other annotations cannot be applied within
Spring Bean(Factory)PostProcessor types, because they themselves
are processed using BeanPostProcessors.  Javadoc and reference docs
have been updated to reflect.

Issue: SPR-4935, SPR-8213

Author: cbeams

org.springframework.beans/src/main/java/org/springframework/beans/factory/annotation/Autowired.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * Copyright 2002-2011 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.
@@ -46,13 +46,20 @@
  * declared value type. In case of a Map, the keys must be declared as
  * type String and will be resolved to the corresponding bean names.
  *
- * <p>Please do consult the javadoc for the {@link AutowiredAnnotationBeanPostProcessor}
+ * <p>Note that actual injection is performed through a
+ * {@link org.springframework.beans.factory.config.BeanPostProcessor
+ * BeanPostProcessor} which in turn means that you <em>cannot</em>
+ * use {@code @Autowired} to inject references into
+ * {@link org.springframework.beans.factory.config.BeanPostProcessor
+ * BeanPostProcessor} or {@link BeanFactoryPostProcessor} types. Please
+ * consult the javadoc for the {@link AutowiredAnnotationBeanPostProcessor}
  * class (which, by default, checks for the presence of this annotation).
  *
  * @author Juergen Hoeller
  * @author Mark Fisher
  * @since 2.5
  * @see AutowiredAnnotationBeanPostProcessor
+ * @see Value
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.METHOD})

org.springframework.beans/src/main/java/org/springframework/beans/factory/annotation/AutowiredAnnotationBeanPostProcessor.java

@@ -62,7 +62,7 @@
  * {@link org.springframework.beans.factory.config.BeanPostProcessor} implementation
  * that autowires annotated fields, setter methods and arbitrary config methods.
  * Such members to be injected are detected through a Java 5 annotation:
- * by default, Spring's {@link Autowired} annotation.
+ * by default, Spring's @{@link Autowired} and @{@link Value} annotations.
  *
  * <p>Only one constructor (at max) of any given bean class may carry this
  * annotation with the 'required' parameter set to <code>true</code>, 
@@ -83,21 +83,23 @@
  * a special case of such a general config method. Such config methods
  * do not have to be public.
  *
- * <p>Also supports JSR-330's {@link javax.inject.Inject} annotation, if available.
+ * <p>Also supports JSR-330's {@link javax.inject.Inject @Inject} annotation, if
+ * available.
  *
  * <p>Note: A default AutowiredAnnotationBeanPostProcessor will be registered
  * by the "context:annotation-config" and "context:component-scan" XML tags.
  * Remove or turn off the default annotation configuration there if you intend
  * to specify a custom AutowiredAnnotationBeanPostProcessor bean definition.
- * <p><b>NOTE:</b> Annotation injection will be performed <i>before</i> XML injection; thus
- * the latter configuration will override the former for properties wired through
- * both approaches. 
- * 
+ * <p><b>NOTE:</b> Annotation injection will be performed <i>before</i> XML injection;
+ * thus the latter configuration will override the former for properties wired through
+ * both approaches.
+ *
  * @author Juergen Hoeller
  * @author Mark Fisher
  * @since 2.5
  * @see #setAutowiredAnnotationType
  * @see Autowired
+ * @see Value
  */
 public class AutowiredAnnotationBeanPostProcessor extends InstantiationAwareBeanPostProcessorAdapter
 		implements MergedBeanDefinitionPostProcessor, PriorityOrdered, BeanFactoryAware {

org.springframework.beans/src/main/java/org/springframework/beans/factory/annotation/Value.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2009 the original author or authors.
+ * Copyright 2002-2011 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.
@@ -31,8 +31,19 @@
  * <p>A common use case is to assign default field values using
  * "#{systemProperties.myProp}" style expressions.
  *
+ * <p>Note that actual processing of the {@code @Value} annotation is performed
+ * by a {@link org.springframework.beans.factory.config.BeanPostProcessor
+ * BeanPostProcessor} which in turn means that you <em>cannot</em> use
+ * {@code @Value} within
+ * {@link org.springframework.beans.factory.config.BeanPostProcessor
+ * BeanPostProcessor} or {@link BeanFactoryPostProcessor} types. Please
+ * consult the javadoc for the {@link AutowiredAnnotationBeanPostProcessor}
+ * class (which, by default, checks for the presence of this annotation).
+ *
  * @author Juergen Hoeller
  * @since 3.0
+ * @see AutowiredAnnotationBeanPostProcessor
+ * @see Value
  * @see org.springframework.beans.factory.config.BeanExpressionResolver
  * @see org.springframework.beans.factory.support.AutowireCandidateResolver#getSuggestedValue
  */

spring-framework-reference/src/beans-annotation-config.xml

@@ -277,6 +277,7 @@
       interfaces that are well-known resolvable dependencies:
       <interfacename>BeanFactory</interfacename>,
       <interfacename>ApplicationContext</interfacename>,
+      <interfacename>Environment</interfacename>,
       <interfacename>ResourceLoader</interfacename>,
       <interfacename>ApplicationEventPublisher</interfacename>, and
       <interfacename>MessageSource</interfacename>. These interfaces and their
@@ -295,6 +296,21 @@
 
   <lineannotation>// ...</lineannotation>
 }</programlisting>
+
+    <note>
+      <para>
+        <interfacename>@Autowired</interfacename>,
+        <interfacename>@Inject</interfacename>,
+        <interfacename>@Resource</interfacename>, and
+        <interfacename>@Value</interfacename> annotations are handled by a
+        Spring <interfacename>BeanPostProcessor</interfacename> implementations
+        which in turn means that you <emphasis>cannot</emphasis>
+        apply these annotations within your own
+        <classname>BeanPostProcessor</classname> or
+        <classname>BeanFactoryPostProcessor</classname> types (if any). These
+        types must be 'wired up' explicitly via XML or using a Spring
+        <interfacename>@Bean</interfacename> method.</para>
+    </note>
   </section>
 
   <section id="beans-autowired-annotation-qualifiers">