Skip to content

Commit 74ddf1b

Browse files
committed
Improve documentation for @Autowired constructors
Prior to this commit, there was some ambiguity surrounding semantics for @Autowired constructors and `required = true`, especially for multiple @Autowired constructors. This commit improves the documentation in the Javadoc for @Autowired as well as in the reference manual. Closes gh-23263
1 parent 99c4a9e commit 74ddf1b

File tree

2 files changed

+27
-21
lines changed

2 files changed

+27
-21
lines changed

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

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2002-2018 the original author or authors.
2+
* Copyright 2002-2019 the original author or authors.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -23,19 +23,21 @@
2323
import java.lang.annotation.Target;
2424

2525
/**
26-
* Marks a constructor, field, setter method or config method as to be autowired by
26+
* Marks a constructor, field, setter method, or config method as to be autowired by
2727
* Spring's dependency injection facilities. This is an alternative to the JSR-330
2828
* {@link javax.inject.Inject} annotation, adding required-vs-optional semantics.
2929
*
30-
* <p>Only one constructor (at max) of any given bean class may declare this annotation
31-
* with the 'required' parameter set to {@code true}, indicating <i>the</i> constructor
32-
* to autowire when used as a Spring bean. If multiple <i>non-required</i> constructors
33-
* declare the annotation, they will be considered as candidates for autowiring.
34-
* The constructor with the greatest number of dependencies that can be satisfied by
35-
* matching beans in the Spring container will be chosen. If none of the candidates
36-
* can be satisfied, then a primary/default constructor (if present) will be used.
37-
* If a class only declares a single constructor to begin with, it will always be used,
38-
* even if not annotated. An annotated constructor does not have to be public.
30+
* <p>Only one constructor of any given bean class may declare this annotation with
31+
* the 'required' attribute set to {@code true}, indicating <i>the</i> constructor
32+
* to autowire when used as a Spring bean. Furthermore, if the 'required' attribute
33+
* is set to {@code true}, only a single constructor may be annotated with
34+
* {@code @Autowired}. If multiple <i>non-required</i> constructors declare the
35+
* annotation, they will be considered as candidates for autowiring. The constructor
36+
* with the greatest number of dependencies that can be satisfied by matching beans
37+
* in the Spring container will be chosen. If none of the candidates can be satisfied,
38+
* then a primary/default constructor (if present) will be used. If a class only
39+
* declares a single constructor to begin with, it will always be used, even if not
40+
* annotated. An annotated constructor does not have to be public.
3941
*
4042
* <p>Fields are injected right after construction of a bean, before any config methods
4143
* are invoked. Such a config field does not have to be public.
@@ -45,7 +47,7 @@
4547
* Bean property setter methods are effectively just a special case of such a general
4648
* config method. Such config methods do not have to be public.
4749
*
48-
* <p>In the case of a multi-arg constructor or method, the 'required' parameter is
50+
* <p>In the case of a multi-arg constructor or method, the 'required' attribute is
4951
* applicable to all arguments. Individual parameters may be declared as Java-8-style
5052
* {@link java.util.Optional} or, as of Spring Framework 5.0, also as {@code @Nullable}
5153
* or a not-null parameter type in Kotlin, overriding the base required semantics.

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

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4811,15 +4811,19 @@ e.g. declared as a single public constructor without an `@Autowired` annotation.
48114811

48124812
[NOTE]
48134813
====
4814-
Only one annotated constructor per class can be marked as required, but multiple
4815-
non-required constructors can be annotated. In that case, each is considered among
4816-
the candidates and Spring uses the greediest constructor whose dependencies can be
4817-
satisfied -- that is, the constructor that has the largest number of arguments.
4818-
The constructor resolution algorithm is the same as for non-annotated classes with
4819-
overloaded constructors, just narrowing the candidates to annotated constructors.
4820-
4821-
The 'required' attribute of `@Autowired` is recommended over the `@Required` annotation
4822-
on setter methods. The 'required' attribute indicates that the property is not required
4814+
Only one constructor of any given bean class may declare `@Autowired` with the `required`
4815+
attribute set to `true`, indicating _the_ constructor to autowire when used as a Spring
4816+
bean. Furthermore, if the `required` attribute is set to `true`, only a single
4817+
constructor may be annotated with `@Autowired`. If multiple _non-required_ constructors
4818+
declare the annotation, they will be considered as candidates for autowiring. The
4819+
constructor with the greatest number of dependencies that can be satisfied by matching
4820+
beans in the Spring container will be chosen. If none of the candidates can be satisfied,
4821+
then a primary/default constructor (if present) will be used. If a class only declares a
4822+
single constructor to begin with, it will always be used, even if not annotated. An
4823+
annotated constructor does not have to be public.
4824+
4825+
The `required` attribute of `@Autowired` is recommended over the `@Required` annotation
4826+
on setter methods. The `required` attribute indicates that the property is not required
48234827
for autowiring purposes. The property is ignored if it cannot be autowired. `@Required`,
48244828
on the other hand, is stronger in that it enforces the property to be set by any means
48254829
supported by the container. If no value is defined, a corresponding exception is raised.

0 commit comments

Comments
 (0)