Merge branch '5.1.x'

Author: sbrannen

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

@@ -28,15 +28,17 @@
  * {@link javax.inject.Inject} annotation, adding required-vs-optional semantics.
  *
  * <h3>Autowired Constructors</h3>
- * <p>Only one constructor (at max) of any given bean class may declare this annotation
- * with the 'required' parameter set to {@code true}, indicating <i>the</i> constructor
- * 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>Only one constructor of any given bean class may declare this annotation with
+ * the 'required' attribute set to {@code true}, indicating <i>the</i> constructor
+ * to autowire when used as a Spring bean. Furthermore, if the 'required' attribute
+ * is set to {@code true}, only a single constructor may be annotated with
+ * {@code @Autowired}. 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.
  *
  * <h3>Autowired Fields</h3>
  * <p>Fields are injected right after construction of a bean, before any config methods

src/docs/asciidoc/core/core-beans.adoc

@@ -4538,15 +4538,19 @@ e.g. declared as a single public constructor without an `@Autowired` annotation.
 
 [NOTE]
 ====
-Only one annotated constructor per class can be marked as required, but multiple
-non-required constructors can be annotated. In that case, each is considered among
-the candidates and Spring uses the greediest constructor whose dependencies can be
-satisfied -- that is, the constructor that has the largest number of arguments.
-The constructor resolution algorithm is the same as for non-annotated classes with
-overloaded constructors, just narrowing the candidates to annotated constructors.
-
-The 'required' attribute of `@Autowired` is recommended over the `@Required` annotation
-on setter methods. The 'required' attribute indicates that the property is not required
+Only one constructor of any given bean class may declare `@Autowired` with the `required`
+attribute set to `true`, indicating _the_ constructor to autowire when used as a Spring
+bean. Furthermore, if the `required` attribute is set to `true`, only a single
+constructor may be annotated with `@Autowired`. If multiple _non-required_ 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.
+
+The `required` attribute of `@Autowired` is recommended over the `@Required` annotation
+on setter methods. The `required` attribute indicates that the property is not required
 for autowiring purposes. The property is ignored if it cannot be autowired. `@Required`,
 on the other hand, is stronger in that it enforces the property to be set by any means
 supported by the container. If no value is defined, a corresponding exception is raised.