[[beans-factory-collaborators]]
= Dependency Injection

Dependency injection (DI) is a process whereby objects define their dependencies
(that is, the other objects with which they work) only through constructor arguments,
arguments to a factory method, or properties that are set on the object instance after
it is constructed or returned from a factory method. The container then injects those
dependencies when it creates the bean. This process is fundamentally the inverse (hence
the name, Inversion of Control) of the bean itself controlling the instantiation
or location of its dependencies on its own by using direct construction of classes or
the Service Locator pattern.

Code is cleaner with the DI principle, and decoupling is more effective when objects are
provided with their dependencies. The object does not look up its dependencies and does
not know the location or class of the dependencies. As a result, your classes become easier
to test, particularly when the dependencies are on interfaces or abstract base classes,
which allow for stub or mock implementations to be used in unit tests.

DI exists in two major variants:
xref:core/beans/dependencies/factory-collaborators.adoc#beans-constructor-injection[Constructor-based dependency injection]
and xref:core/beans/dependencies/factory-collaborators.adoc#beans-setter-injection[Setter-based dependency injection].


[[beans-constructor-injection]]
== Constructor-based Dependency Injection

Constructor-based DI is accomplished by the container invoking a constructor with a
number of arguments, each representing a dependency. Calling a `static` factory method
with specific arguments to construct the bean is nearly equivalent, and this discussion
treats arguments to a constructor and to a `static` factory method similarly. The
following example shows a class that can only be dependency-injected with constructor
injection:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes"]
----
	public class SimpleMovieLister {

		// the SimpleMovieLister has a dependency on a MovieFinder
		private final MovieFinder movieFinder;

		// a constructor so that the Spring container can inject a MovieFinder
		public SimpleMovieLister(MovieFinder movieFinder) {
			this.movieFinder = movieFinder;
		}

		// business logic that actually uses the injected MovieFinder is omitted...
	}
----

Kotlin::
+
[source,kotlin,indent=0,subs="verbatim,quotes"]
----
	// a constructor so that the Spring container can inject a MovieFinder
	class SimpleMovieLister(private val movieFinder: MovieFinder) {
		// business logic that actually uses the injected MovieFinder is omitted...
	}
----
======

Notice that there is nothing special about this class. It is a POJO that
has no dependencies on container specific interfaces, base classes, or annotations.

[[beans-factory-ctor-arguments-resolution]]
=== Constructor Argument Resolution

Constructor argument resolution matching occurs by using the argument's type. If no
potential ambiguity exists in the constructor arguments of a bean definition, the
order in which the constructor arguments are defined in a bean definition is the order
in which those arguments are supplied to the appropriate constructor when the bean is
being instantiated. Consider the following class:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"]
----
	package x.y;

	public class ThingOne {

		public ThingOne(ThingTwo thingTwo, ThingThree thingThree) {
			// ...
		}
	}
----

Kotlin::
+
[source,kotlin,indent=0,subs="verbatim,quotes",chomp="-packages"]
----
	package x.y

	class ThingOne(thingTwo: ThingTwo, thingThree: ThingThree)
----
======

Assuming that the `ThingTwo` and `ThingThree` classes are not related by inheritance, no
potential ambiguity exists. Thus, the following configuration works fine, and you do not
need to specify the constructor argument indexes or types explicitly in the
`<constructor-arg/>` element.

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<beans>
		<bean id="beanOne" class="x.y.ThingOne">
			<constructor-arg ref="beanTwo"/>
			<constructor-arg ref="beanThree"/>
		</bean>

		<bean id="beanTwo" class="x.y.ThingTwo"/>

		<bean id="beanThree" class="x.y.ThingThree"/>
	</beans>
----

When another bean is referenced, the type is known, and matching can occur (as was the
case with the preceding example). When a simple type is used, such as
`<value>true</value>`, Spring cannot determine the type of the value, and so cannot match
by type without help. Consider the following class:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"]
----
	package examples;

	public class ExampleBean {

		// Number of years to calculate the Ultimate Answer
		private final int years;

		// The Answer to Life, the Universe, and Everything
		private final String ultimateAnswer;

		public ExampleBean(int years, String ultimateAnswer) {
			this.years = years;
			this.ultimateAnswer = ultimateAnswer;
		}
	}
----

Kotlin::
+
[source,kotlin,indent=0,subs="verbatim,quotes",chomp="-packages"]
----
	package examples

	class ExampleBean(
		private val years: Int, // Number of years to calculate the Ultimate Answer
		private val ultimateAnswer: String // The Answer to Life, the Universe, and Everything
	)
----
======

[discrete]
[[beans-factory-ctor-arguments-type]]
==== Constructor argument type matching

In the preceding scenario, the container can use type matching with simple types if
you explicitly specify the type of the constructor argument via the `type` attribute,
as the following example shows:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<bean id="exampleBean" class="examples.ExampleBean">
		<constructor-arg type="int" value="7500000"/>
		<constructor-arg type="java.lang.String" value="42"/>
	</bean>
----

[discrete]
[[beans-factory-ctor-arguments-index]]
==== Constructor argument index

You can use the `index` attribute to specify explicitly the index of constructor arguments,
as the following example shows:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<bean id="exampleBean" class="examples.ExampleBean">
		<constructor-arg index="0" value="7500000"/>
		<constructor-arg index="1" value="42"/>
	</bean>
----

In addition to resolving the ambiguity of multiple simple values, specifying an index
resolves ambiguity where a constructor has two arguments of the same type.

NOTE: The index is 0-based.

[discrete]
[[beans-factory-ctor-arguments-name]]
==== Constructor argument name

You can also use the constructor parameter name for value disambiguation, as the following
example shows:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<bean id="exampleBean" class="examples.ExampleBean">
		<constructor-arg name="years" value="7500000"/>
		<constructor-arg name="ultimateAnswer" value="42"/>
	</bean>
----

Keep in mind that, to make this work out of the box, your code must be compiled with the
`-parameters` flag enabled so that Spring can look up the parameter name from the constructor.
If you cannot or do not want to compile your code with the `-parameters` flag, you can use the
https://download.oracle.com/javase/8/docs/api/java/beans/ConstructorProperties.html[@ConstructorProperties]
JDK annotation to explicitly name your constructor arguments. The sample class would
then have to look as follows:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"]
----
	package examples;

	public class ExampleBean {

		// Fields omitted

		@ConstructorProperties({"years", "ultimateAnswer"})
		public ExampleBean(int years, String ultimateAnswer) {
			this.years = years;
			this.ultimateAnswer = ultimateAnswer;
		}
	}
----

Kotlin::
+
[source,kotlin,indent=0,subs="verbatim,quotes",chomp="-packages"]
----
	package examples

	class ExampleBean
	@ConstructorProperties("years", "ultimateAnswer")
	constructor(val years: Int, val ultimateAnswer: String)
----
======


[[beans-setter-injection]]
== Setter-based Dependency Injection

Setter-based DI is accomplished by the container calling setter methods on your
beans after invoking a no-argument constructor or a no-argument `static` factory method to
instantiate your bean.

The following example shows a class that can only be dependency-injected by using pure
setter injection. This class is conventional Java. It is a POJO that has no dependencies
on container specific interfaces, base classes, or annotations.

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes"]
----
	public class SimpleMovieLister {

		// the SimpleMovieLister has a dependency on the MovieFinder
		private MovieFinder movieFinder;

		// a setter method so that the Spring container can inject a MovieFinder
		public void setMovieFinder(MovieFinder movieFinder) {
			this.movieFinder = movieFinder;
		}

		// business logic that actually uses the injected MovieFinder is omitted...
	}
----

Kotlin::
+
[source,kotlin,indent=0,subs="verbatim,quotes"]
----
class SimpleMovieLister {

	// a late-initialized property so that the Spring container can inject a MovieFinder
	lateinit var movieFinder: MovieFinder

	// business logic that actually uses the injected MovieFinder is omitted...
}
----
======


The `ApplicationContext` supports constructor-based and setter-based DI for the beans it
manages. It also supports setter-based DI after some dependencies have already been
injected through the constructor approach. You configure the dependencies in the form of
a `BeanDefinition`, which you use in conjunction with `PropertyEditor` instances to
convert properties from one format to another. However, most Spring users do not work
with these classes directly (that is, programmatically) but rather with XML `bean`
definitions, annotated components (that is, classes annotated with `@Component`,
`@Controller`, and so forth), or `@Bean` methods in Java-based `@Configuration` classes.
These sources are then converted internally into instances of `BeanDefinition` and used to
load an entire Spring IoC container instance.

[[beans-constructor-vs-setter-injection]]
.Constructor-based or setter-based DI?
****
Since you can mix constructor-based and setter-based DI, it is a good rule of thumb to
use constructors for mandatory dependencies and setter methods or configuration methods
for optional dependencies. Note that use of the xref:core/beans/annotation-config/autowired.adoc[@Autowired]
annotation on a setter method can be used to make the property be a required dependency;
however, constructor injection with programmatic validation of arguments is preferable.

The Spring team generally advocates constructor injection, as it lets you implement
application components as immutable objects and ensures that required dependencies
are not `null`. Furthermore, constructor-injected components are always returned to the client
(calling) code in a fully initialized state. As a side note, a large number of constructor
arguments is a bad code smell, implying that the class likely has too many
responsibilities and should be refactored to better address proper separation of concerns.

Setter injection should primarily only be used for optional dependencies that can be
assigned reasonable default values within the class. Otherwise, not-null checks must be
performed everywhere the code uses the dependency. One benefit of setter injection is that
setter methods make objects of that class amenable to reconfiguration or re-injection
later. Management through xref:integration/jmx.adoc[JMX MBeans] is therefore a compelling
use case for setter injection.

Use the DI style that makes the most sense for a particular class. Sometimes, when dealing
with third-party classes for which you do not have the source, the choice is made for you.
For example, if a third-party class does not expose any setter methods, then constructor
injection may be the only available form of DI.
****


[[beans-dependency-resolution]]
== Dependency Resolution Process

The container performs bean dependency resolution as follows:

* The `ApplicationContext` is created and initialized with configuration metadata that
  describes all the beans. Configuration metadata can be specified by XML, Java code, or
  annotations.
* For each bean, its dependencies are expressed in the form of properties, constructor
  arguments, or arguments to the static-factory method (if you use that instead of a
  normal constructor). These dependencies are provided to the bean, when the bean is
  actually created.
* Each property or constructor argument is an actual definition of the value to set, or
  a reference to another bean in the container.
* Each property or constructor argument that is a value is converted from its specified
  format to the actual type of that property or constructor argument. By default, Spring
  can convert a value supplied in string format to all built-in types, such as `int`,
  `long`, `String`, `boolean`, and so forth.

The Spring container validates the configuration of each bean as the container is created.
However, the bean properties themselves are not set until the bean is actually created.
Beans that are singleton-scoped and set to be pre-instantiated (the default) are created
when the container is created. Scopes are defined in xref:core/beans/factory-scopes.adoc[Bean Scopes]. Otherwise,
the bean is created only when it is requested. Creation of a bean potentially causes a
graph of beans to be created, as the bean's dependencies and its dependencies'
dependencies (and so on) are created and assigned. Note that resolution mismatches among
those dependencies may show up late -- that is, on first creation of the affected bean.

.Circular dependencies
****
If you use predominantly constructor injection, it is possible to create an unresolvable
circular dependency scenario.

For example: Class A requires an instance of class B through constructor injection, and
class B requires an instance of class A through constructor injection. If you configure
beans for classes A and B to be injected into each other, the Spring IoC container
detects this circular reference at runtime, and throws a
`BeanCurrentlyInCreationException`.

One possible solution is to edit the source code of some classes to be configured by
setters rather than constructors. Alternatively, avoid constructor injection and use
setter injection only. In other words, although it is not recommended, you can configure
circular dependencies with setter injection.

Unlike the typical case (with no circular dependencies), a circular dependency
between bean A and bean B forces one of the beans to be injected into the other prior to
being fully initialized itself (a classic chicken-and-egg scenario).
****

You can generally trust Spring to do the right thing. It detects configuration problems,
such as references to non-existent beans and circular dependencies, at container
load-time. Spring sets properties and resolves dependencies as late as possible, when
the bean is actually created. This means that a Spring container that has loaded
correctly can later generate an exception when you request an object if there is a
problem creating that object or one of its dependencies -- for example, the bean throws an
exception as a result of a missing or invalid property. This potentially delayed
visibility of some configuration issues is why `ApplicationContext` implementations by
default pre-instantiate singleton beans. At the cost of some upfront time and memory to
create these beans before they are actually needed, you discover configuration issues
when the `ApplicationContext` is created, not later. You can still override this default
behavior so that singleton beans initialize lazily, rather than being eagerly
pre-instantiated.

If no circular dependencies exist, when one or more collaborating beans are being
injected into a dependent bean, each collaborating bean is totally configured prior
to being injected into the dependent bean. This means that, if bean A has a dependency on
bean B, the Spring IoC container completely configures bean B prior to invoking the
setter method on bean A. In other words, the bean is instantiated (if it is not a
pre-instantiated singleton), its dependencies are set, and the relevant lifecycle
methods (such as a xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[configured init method]
or the xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[InitializingBean callback method])
are invoked.


[[beans-some-examples]]
== Examples of Dependency Injection

The following example uses XML-based configuration metadata for setter-based DI. A small
part of a Spring XML configuration file specifies some bean definitions as follows:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<bean id="exampleBean" class="examples.ExampleBean">
		<!-- setter injection using the nested ref element -->
		<property name="beanOne">
			<ref bean="anotherExampleBean"/>
		</property>

		<!-- setter injection using the neater ref attribute -->
		<property name="beanTwo" ref="yetAnotherBean"/>
		<property name="integerProperty" value="1"/>
	</bean>

	<bean id="anotherExampleBean" class="examples.AnotherBean"/>
	<bean id="yetAnotherBean" class="examples.YetAnotherBean"/>
----

The following example shows the corresponding `ExampleBean` class:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes"]
----
	public class ExampleBean {

		private AnotherBean beanOne;

		private YetAnotherBean beanTwo;

		private int i;

		public void setBeanOne(AnotherBean beanOne) {
			this.beanOne = beanOne;
		}

		public void setBeanTwo(YetAnotherBean beanTwo) {
			this.beanTwo = beanTwo;
		}

		public void setIntegerProperty(int i) {
			this.i = i;
		}
	}
----

Kotlin::
+
[source,kotlin,indent=0,subs="verbatim,quotes"]
----
class ExampleBean {
	lateinit var beanOne: AnotherBean
	lateinit var beanTwo: YetAnotherBean
	var i: Int = 0
}
----
======

In the preceding example, setters are declared to match against the properties specified
in the XML file. The following example uses constructor-based DI:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<bean id="exampleBean" class="examples.ExampleBean">
		<!-- constructor injection using the nested ref element -->
		<constructor-arg>
			<ref bean="anotherExampleBean"/>
		</constructor-arg>

		<!-- constructor injection using the neater ref attribute -->
		<constructor-arg ref="yetAnotherBean"/>

		<constructor-arg type="int" value="1"/>
	</bean>

	<bean id="anotherExampleBean" class="examples.AnotherBean"/>
	<bean id="yetAnotherBean" class="examples.YetAnotherBean"/>
----

The following example shows the corresponding `ExampleBean` class:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes"]
----
	public class ExampleBean {

		private AnotherBean beanOne;

		private YetAnotherBean beanTwo;

		private int i;

		public ExampleBean(
			AnotherBean anotherBean, YetAnotherBean yetAnotherBean, int i) {
			this.beanOne = anotherBean;
			this.beanTwo = yetAnotherBean;
			this.i = i;
		}
	}
----

Kotlin::
+
[source,kotlin,indent=0,subs="verbatim,quotes"]
----
class ExampleBean(
		private val beanOne: AnotherBean,
		private val beanTwo: YetAnotherBean,
		private val i: Int)
----
======

The constructor arguments specified in the bean definition are used as arguments to
the constructor of the `ExampleBean`.

Now consider a variant of this example, where, instead of using a constructor, Spring is
told to call a `static` factory method to return an instance of the object:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<bean id="exampleBean" class="examples.ExampleBean" factory-method="createInstance">
		<constructor-arg ref="anotherExampleBean"/>
		<constructor-arg ref="yetAnotherBean"/>
		<constructor-arg value="1"/>
	</bean>

	<bean id="anotherExampleBean" class="examples.AnotherBean"/>
	<bean id="yetAnotherBean" class="examples.YetAnotherBean"/>
----

The following example shows the corresponding `ExampleBean` class:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes"]
----
	public class ExampleBean {

		// a private constructor
		private ExampleBean(...) {
			...
		}

		// a static factory method; the arguments to this method can be
		// considered the dependencies of the bean that is returned,
		// regardless of how those arguments are actually used.
		public static ExampleBean createInstance (
			AnotherBean anotherBean, YetAnotherBean yetAnotherBean, int i) {

			ExampleBean eb = new ExampleBean (...);
			// some other operations...
			return eb;
		}
	}
----

Kotlin::
+
[source,kotlin,indent=0,subs="verbatim,quotes"]
----
	class ExampleBean private constructor() {
		companion object {
			// a static factory method; the arguments to this method can be
			// considered the dependencies of the bean that is returned,
			// regardless of how those arguments are actually used.
			@JvmStatic
			fun createInstance(anotherBean: AnotherBean, yetAnotherBean: YetAnotherBean, i: Int): ExampleBean {
				val eb = ExampleBean (...)
				// some other operations...
				return eb
			}
		}
	}
----
======

Arguments to the `static` factory method are supplied by `<constructor-arg/>` elements,
exactly the same as if a constructor had actually been used. The type of the class being
returned by the factory method does not have to be of the same type as the class that
contains the `static` factory method (although, in this example, it is). An instance
(non-static) factory method can be used in an essentially identical fashion (aside
from the use of the `factory-bean` attribute instead of the `class` attribute), so we
do not discuss those details here.
