Revised javadoc for up-to-date constructor autowiring semantics

Issue: SPR-17299

(cherry picked from commit 333e327289)

spring-beans/src/main/java/org/springframework/beans/factory/Aware.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2011 the original author or authors.
+ * Copyright 2002-2018 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,21 +17,19 @@
 package org.springframework.beans.factory;
 
 /**
- * Marker superinterface indicating that a bean is eligible to be
+ * A marker superinterface indicating that a bean is eligible to be notified by the
- * notified by the Spring container of a particular framework object
+ * Spring container of a particular framework object through a callback-style method.
- * through a callback-style method. Actual method signature is
+ * The actual method signature is determined by individual subinterfaces but should
- * determined by individual subinterfaces, but should typically
+ * typically consist of just one void-returning method that accepts a single argument.
- * consist of just one void-returning method that accepts a single
- * argument.
  *
- * <p>Note that merely implementing {@link Aware} provides no default
+ * <p>Note that merely implementing {@link Aware} provides no default functionality.
- * functionality. Rather, processing must be done explicitly, for example
+ * Rather, processing must be done explicitly, for example in a
- * in a {@link org.springframework.beans.factory.config.BeanPostProcessor BeanPostProcessor}.
+ * {@link org.springframework.beans.factory.config.BeanPostProcessor}.
  * Refer to {@link org.springframework.context.support.ApplicationContextAwareProcessor}
- * and {@link org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory}
+ * for an example of processing specific {@code *Aware} interface callbacks.
- * for examples of processing {@code *Aware} interface callbacks.
  *
  * @author Chris Beams
+ * @author Juergen Hoeller
  * @since 3.1
  */
 public interface Aware {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -23,15 +23,22 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Marks a constructor, field, setter method or config method as to be autowired
+ * Marks a constructor, field, setter method or config method as to be autowired by
- * by Spring's dependency injection facilities.
+ * Spring's dependency injection facilities. This is an alternative to the JSR-330
+ * {@link javax.inject.Inject} annotation, adding required-vs-optional semantics.
  *
- * <p>Only one constructor (at max) of any given bean class may carry this annotation,
+ * <p>Only one constructor (at max) of any given bean class may declare this annotation
- * indicating the constructor to autowire when used as a Spring bean. Such a
+ * with the 'required' parameter set to {@code true}, indicating <i>the</i> constructor
- * constructor does not have to be public.
+ * to autowire when used as a Spring bean. If multiple <i>non-required</i> constructors
+ * declare the annotation, they will be considered as candidates for autowiring.
+ * The constructor with the greatest number of dependencies that can be satisfied by
+ * matching beans in the Spring container will be chosen. If none of the candidates
+ * can be satisfied, then a primary/default constructor (if present) will be used.
+ * If a class only declares a single constructor to begin with, it will always be used,
+ * even if not annotated. An annotated constructor does not have to be public.
  *
- * <p>Fields are injected right after construction of a bean, before any config
+ * <p>Fields are injected right after construction of a bean, before any config methods
- * methods are invoked. Such a config field does not have to be public.
+ * are invoked. Such a config field does not have to be public.
  *
  * <p>Config methods may have an arbitrary name and any number of arguments; each of
  * those arguments will be autowired with a matching bean in the Spring container.

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

@@ -74,15 +74,15 @@ import org.springframework.util.StringUtils;
  * <p>Also supports JSR-330's {@link javax.inject.Inject @Inject} annotation,
  * if available, as a direct alternative to Spring's own {@code @Autowired}.
  *
- * <p>Only one constructor (at max) of any given bean class may carry this
+ * <p>Only one constructor (at max) of any given bean class may declare this annotation
- * annotation with the 'required' parameter set to {@code true},
+ * with the 'required' parameter set to {@code true}, indicating <i>the</i> constructor
- * indicating <i>the</i> constructor to autowire when used as a Spring bean.
+ * to autowire when used as a Spring bean. If multiple <i>non-required</i> constructors
- * If multiple <i>non-required</i> constructors carry the annotation, they
+ * declare the annotation, they will be considered as candidates for autowiring.
- * will be considered as candidates for autowiring. The constructor with
+ * The constructor with the greatest number of dependencies that can be satisfied by
- * the greatest number of dependencies that can be satisfied by matching
+ * matching beans in the Spring container will be chosen. If none of the candidates
- * beans in the Spring container will be chosen. If none of the candidates
+ * can be satisfied, then a primary/default constructor (if present) will be used.
- * can be satisfied, then a default constructor (if present) will be used.
+ * If a class only declares a single constructor to begin with, it will always be used,
- * An annotated constructor does not have to be public.
+ * even if not annotated. An annotated constructor does not have to be public.
  *
  * <p>Fields are injected right after construction of a bean, before any
  * config methods are invoked. Such a config field does not have to be public.
@@ -161,11 +161,11 @@ public class AutowiredAnnotationBeanPostProcessor extends InstantiationAwareBean
 	/**
 	 * Set the 'autowired' annotation type, to be used on constructors, fields,
 	 * setter methods and arbitrary config methods.
-	 * <p>The default autowired annotation type is the Spring-provided
+	 * <p>The default autowired annotation type is the Spring-provided {@link Autowired}
-	 * {@link Autowired} annotation, as well as {@link Value}.
+	 * annotation, as well as {@link Value}.
 	 * <p>This setter property exists so that developers can provide their own
-	 * (non-Spring-specific) annotation type to indicate that a member is
+	 * (non-Spring-specific) annotation type to indicate that a member is supposed
-	 * supposed to be autowired.
+	 * to be autowired.
 	 */
 	public void setAutowiredAnnotationType(Class<? extends Annotation> autowiredAnnotationType) {
 		Assert.notNull(autowiredAnnotationType, "'autowiredAnnotationType' must not be null");
@@ -176,11 +176,11 @@ public class AutowiredAnnotationBeanPostProcessor extends InstantiationAwareBean
 	/**
 	 * Set the 'autowired' annotation types, to be used on constructors, fields,
 	 * setter methods and arbitrary config methods.
-	 * <p>The default autowired annotation type is the Spring-provided
+	 * <p>The default autowired annotation type is the Spring-provided {@link Autowired}
-	 * {@link Autowired} annotation, as well as {@link Value}.
+	 * annotation, as well as {@link Value}.
 	 * <p>This setter property exists so that developers can provide their own
-	 * (non-Spring-specific) annotation types to indicate that a member is
+	 * (non-Spring-specific) annotation types to indicate that a member is supposed
-	 * supposed to be autowired.
+	 * to be autowired.
 	 */
 	public void setAutowiredAnnotationTypes(Set<Class<? extends Annotation>> autowiredAnnotationTypes) {
 		Assert.notEmpty(autowiredAnnotationTypes, "'autowiredAnnotationTypes' must not be empty");
@@ -189,8 +189,7 @@ public class AutowiredAnnotationBeanPostProcessor extends InstantiationAwareBean
 	}
 
 	/**
-	 * Set the name of a parameter of the annotation that specifies
+	 * Set the name of a parameter of the annotation that specifies whether it is required.
-	 * whether it is required.
 	 * @see #setRequiredParameterValue(boolean)
 	 */
 	public void setRequiredParameterName(String requiredParameterName) {
@@ -199,9 +198,8 @@ public class AutowiredAnnotationBeanPostProcessor extends InstantiationAwareBean
 
 	/**
 	 * Set the boolean value that marks a dependency as required
-	 * <p>For example if using 'required=true' (the default),
+	 * <p>For example if using 'required=true' (the default), this value should be
-	 * this value should be {@code true}; but if using
+	 * {@code true}; but if using 'optional=false', this value should be {@code false}.
-	 * 'optional=false', this value should be {@code false}.
 	 * @see #setRequiredParameterName(String)
 	 */
 	public void setRequiredParameterValue(boolean requiredParameterValue) {