Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve documentation for @Autowired constructors

Browse Source 
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
This commit is contained in:
Sam Brannen
2019-07-17 18:55:58 +02:00
parent e5a28f81c3
commit 6e20f8d0a5
2 changed files with 29 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,5 +1,5 @@
/*
* Copyright 2002-2018 the original author or authors.
* Copyright 2002-2019 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,19 +23,21 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Marks a constructor, field, setter method or config method as to be autowired by
* Marks a constructor, field, setter method, or config method as to be autowired by
* 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 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 standard 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.
*
* <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.
@@ -45,7 +47,7 @@ import java.lang.annotation.Target;
* Bean property setter methods are effectively just a special case of such a general
* config method. Such config methods do not have to be public.
*
* <p>In the case of a multi-arg constructor or method, the 'required' parameter is
* <p>In the case of a multi-arg constructor or method, the 'required' attribute is
* applicable to all arguments. Individual parameters may be declared as Java-8-style
* {@link java.util.Optional}, overriding the base required semantics.
*