consistent specification of standard meta-annotations

jhoeller · jhoeller · commit d64dd1943f4f · 2011-12-03T15:47:29.000Z
diff --git a/org.springframework.beans/src/main/java/org/springframework/beans/factory/annotation/Autowired.java b/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.
@@ -16,6 +16,7 @@
 
 package org.springframework.beans.factory.annotation;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -46,16 +47,25 @@
  * 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 Qualifier
+ * @see Value
  */
-@Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
 public @interface Autowired {
 
 	/**
diff --git a/org.springframework.beans/src/main/java/org/springframework/beans/factory/annotation/Configurable.java b/org.springframework.beans/src/main/java/org/springframework/beans/factory/annotation/Configurable.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2007 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.
@@ -34,10 +34,10 @@
  * @author Ramnivas Laddad
  * @since 2.0
  */
-@Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
-@Documented
+@Retention(RetentionPolicy.RUNTIME)
 @Inherited
+@Documented
 public @interface Configurable {
 
 	/**
diff --git a/org.springframework.beans/src/main/java/org/springframework/beans/factory/annotation/Qualifier.java b/org.springframework.beans/src/main/java/org/springframework/beans/factory/annotation/Qualifier.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.
@@ -31,9 +31,10 @@
  * @author Mark Fisher
  * @author Juergen Hoeller
  * @since 2.5
+ * @see Autowired
  */
-@Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE, ElementType.ANNOTATION_TYPE})
+@Retention(RetentionPolicy.RUNTIME)
 @Inherited
 @Documented
 public @interface Qualifier {
diff --git a/org.springframework.beans/src/main/java/org/springframework/beans/factory/annotation/Value.java b/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.
@@ -16,6 +16,7 @@
 
 package org.springframework.beans.factory.annotation;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -31,13 +32,25 @@
  * <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 Autowired
  * @see org.springframework.beans.factory.config.BeanExpressionResolver
  * @see org.springframework.beans.factory.support.AutowireCandidateResolver#getSuggestedValue
  */
-@Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
 public @interface Value {
 
 	/**
