Spring Beans Discovery through Java Config in Practice

Spring Java Config is a great tool that gives us a precise way to control an application's bootstrap and wiring. However, it only sometimes works as expected. We occasionally run into strange issues where a particular bean is not instantiated at the expected time, lazy loading does not work as expected, or the whole configuration is ignored for no apparent reason.

To get a better understanding of the inner workings of Spring bean discovery, I created some examples that can be found here: https://github.com/maciejmiklas/spring-context-test.git

Each example has a name: exa (example A) or exb (example B). Each example has several exercises, like exa has: exa01, exa02, ..., ex05.

Bean Loading Order - Single Config

https://github.com/maciejmiklas/spring-context-test/tree/master/src/main/java/org/test/context/exa

exa01

This is the first exercise. It defines a basic structure that will be modified as we go along.
The main method loads Spring context from the configuration file Conf.java. This configuration instructs Spring to create 3 beans. Each of these beans has two log statements, the first in the constructor and the second in @PostConstruct. The console output after the execution of this example is shown below the code.

	class ApplicationExA01 {
	public static void main(String[] args) {
	AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
	ctx.register(Conf.class);
	ctx.refresh();
	}
	}
	@Configuration
	class Conf {
	@Bean
	BeanA beanA() { return new BeanA(); }
	@Bean
	BeanB beanB() { return new BeanB(); }
	@Bean
	BeanC beanC() { return new BeanC(); }
	}
	class BeanA {
	public BeanA() {
	log("BeanA - constructor");
	}
	@PostConstruct
	public void postConstruct() {
	log("BeanA - postConstruct");
	}
	}
	class BeanB {
	public BeanB() {
	log("BeanB - constructor");
	}
	@PostConstruct
	public void postConstruct() {
	log("BeanB - postConstruct");
	}
	}
	class BeanC {
	public BeanC() {
	log("BeanC - constructor");
	}
	@PostConstruct
	public void postConstruct() {
	log("BeanC - postConstruct");
	}
	}

view raw exa01.java hosted with ❤ by GitHub

	>> BeanA - constructor
	>> BeanA - postConstruct
	>> BeanB - constructor
	>> BeanB - postConstruct
	>> BeanC - constructor
	>> BeanC - postConstruct

view raw log.log hosted with ❤ by GitHub

Nothing spectacular happens here: beans are initialized from A to C right after the constructor Spring executes also @PostConstruct. There are no dependencies between the beans.

exa02

Let's modify the order of factory methods in Conf.java.

	@Configuration
	class Conf {
	@Bean
	BeanB beanB() {
	return new BeanB();
	}
	@Bean
	BeanA beanA() {
	return new BeanA();
	}
	@Bean
	BeanC beanC() {
	return new BeanC();
	}
	}

view raw exa02.java hosted with ❤ by GitHub

	>> BeanB - constructor
	>> BeanB - postConstruct
	>> BeanA - constructor
	>> BeanA - postConstruct
	>> BeanC - constructor
	>> BeanC - postConstruct

view raw log.log hosted with ❤ by GitHub

The bean initialization order has changed. It means that method names do not matter, but the physical order within a class. It can change with JVM, so you should not rely on it!

exa03

Now we will extract the definition of BeanB into a dedicated configuration file:

	@Import({ConfBeanB.class})
	@Configuration
	class Conf {
	@Bean
	BeanA beanA() {
	return new BeanA();
	}
	@Bean
	BeanC beanC() {
	return new BeanC();
	}
	}
	@Configuration
	class ConfBeanB {
	@Bean
	BeanB beanB() {
	return new BeanB();
	}
	}

view raw exa03.java hosted with ❤ by GitHub

	>> BeanB - constructor
	>> BeanB - postConstruct
	>> BeanA - constructor
	>> BeanA - postConstruct
	>> BeanC - constructor
	>> BeanC - postConstruct

view raw log hosted with ❤ by GitHub

Spring loads bean definitions from the imported configuration in the first place.

exa04

We will modify the previous exercise so that BeanB depends on BeanA.

	@Configuration
	class ConfBeanB {
	@Bean
	@DependsOn("beanA")
	BeanB beanB() {
	return new BeanB();
	}
	}

view raw exa04.java hosted with ❤ by GitHub

	>> BeanA - constructor
	>> BeanA - postConstruct
	>> BeanB - constructor
	>> BeanB - postConstruct
	>> BeanC - constructor
	>> BeanC - postConstruct

view raw log hosted with ❤ by GitHub

Spring loads dependent beans in the first place. It does not matter where it's located. Spring will scan all possible configurations to find it.

exa05

The same as exa04, but BeanB does not have @DependsOn("beanA"). Instead, BeanB injects BeanA. We have a similar dependency situation to exa4: BanB depends on BeanA. However @PostConstructs are called in a different order: Spring creates an instance of BeanB, and during the construction phase (constructor), references to BeanA are not set. Once the instance of BeanB is created, BeanA will be created and injected into BeanB. BeanB cannot access BeanA in the constructor, first after a complete initialization is done - in the method @PostConstruct.
Spring had to modify the order of @PostConstruct calls to ensure that the bean references were not null during an initialization phase.

Summary

• within a single configuration class, the bean instantiation order depends only on the methods order within this class, not method names. However, this might depend on JVM,
• Spring loads, in the first place, imported bean definitions. The previous rule applies only to the situation where direct bean definitions do not depend on imported beans. If this is the case, Spring will load the dependent bean in the first place,
• the initialization code has to be placed in the @PostConstruct method and not in a constructor. Otherwise, references to some beans might be null.

Bean Loading Order - Mixed Config

https://github.com/maciejmiklas/spring-context-test/tree/master/src/main/java/org/test/context/exb

exb01

BeanA, BeanB, and BeanC are created through dedicated configuration classes: ConfBeanA, ConfBeanB, and ConfBeanC. BeanD is declared in Conf 

	class ApplicationExB01 {
	public static void main(String[] args) {
	AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
	ctx.register(Conf.class);
	ctx.refresh();
	log("Call BeanA");
	BeanA beanA = ctx.getBean(BeanA.class);
	beanA.method();
	}
	}
	@Import({ConfBeanA.class, ConfBeanB.class, ConfBeanC.class})
	@Configuration
	class Conf {
	@Bean
	BeanD beanD() {
	return new BeanD();
	}
	}
	class BeanA {
	public BeanA() {
	log("BeanA - constructor");
	}
	@PostConstruct
	public void postConstruct() {
	log("BeanA - postConstruct");
	}
	public void method() {
	log("BeanA - method");
	}
	}
	class BeanB {
	public BeanB() {
	log("BeanB - constructor");
	}
	@PostConstruct
	public void postConstruct() {
	log("BeanB - postConstruct");
	}
	public void method() {
	log("BeanB - method");
	}
	}
	class BeanC {
	public BeanC() {
	log("BeanC - constructor");
	}
	@PostConstruct
	public void postConstruct() {
	log("BeanC - postConstruct");
	}
	public void method() {
	log("BeanC - method");
	}
	}
	class BeanD {
	public BeanD() {
	log("BeanD - constructor");
	}
	@PostConstruct
	public void postConstruct() {
	log("BeanD - postConstruct");
	}
	public void method() {
	log("BeanD - method");
	}
	}
	@Configuration
	class ConfBeanA {
	@Bean
	BeanA beanA() {
	return new BeanA();
	}
	}
	@Configuration
	class ConfBeanB {
	@Bean
	BeanB beanB() {
	return new BeanB();
	}
	}
	@Configuration
	class ConfBeanC {
	@Bean
	BeanC beanC() {
	return new BeanC();
	}
	}

view raw exb01.java hosted with ❤ by GitHub

	>> BeanA - constructor
	>> BeanA - postConstruct
	>> BeanB - constructor
	>> BeanB - postConstruct
	>> BeanC - constructor
	>> BeanC - postConstruct
	>> BeanD - constructor
	>> BeanD - postConstruct
	>> Call BeanA
	>> BeanA - method

view raw log hosted with ❤ by GitHub

Beans are created in order: A, B, C, D.

exb02

Similar to exb01, but the configuration class ConfBeanB has been renamed to ConfBeanXB.

	@Configuration
	class ConfBeanXB {
	@Bean
	BeanB beanB() {
	return new BeanB();
	}
	}

view raw exb02.java hosted with ❤ by GitHub

	>> BeanA - constructor
	>> BeanA - postConstruct
	>> BeanB - constructor
	>> BeanB - postConstruct
	>> BeanC - constructor
	>> BeanC - postConstruct
	>> BeanD - constructor
	>> BeanD - postConstruct
	>> Call BeanA
	>> BeanA - method

view raw log hosted with ❤ by GitHub

The instantiation order remains unchanged.

exb03

The same as exb01, but the factory method in ConfBeanB has been renamed from beanB to xyz. The instantiation order remains unchanged.

exb04

The same as exb01, but BeanB has been renamed to BeanXB. This change did not influence instantiation order.

exb05

Similar to exb01, but we've changed the import order from A, B, C into B, A, C. The instantiation order has changed as well.

exb06

Same as exb01, but BeanC has been injected into BeanA. The instantiation order has been changed because BeanC had to be created before BeanA

Summary

• when the @Import statement contains multiple classes, Spring will load them from the left to the right side - it's iterating over an array, and names of configuration classes do not matter in this case,
• within single configuration class physical order of methods matters, not their names.

Duplicated Bean Name

exc01

We have 3 beans, A, B, and C, with dedicated config here. BeanA injects BeanB and BeanC.

	class ApplicationExC01 {
	public static void main(String[] args) {
	AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
	ctx.register(Conf.class);
	ctx.refresh();
	log("Call BeanA");
	BeanA beanA = ctx.getBean(BeanA.class);
	beanA.method();
	}
	}
	class BeanA {
	@Autowired
	private BeanC beanC;
	@Autowired
	private BeanB beanB;
	public BeanA() {
	log("BeanA - constructor, beanB:%s, beanC:%s", beanB, beanC);
	}
	@PostConstruct
	public void postConstruct() {
	log("BeanA - postConstruct, beanB:%s, beanC:%s", beanB, beanC);
	}
	public void method() {
	log("BeanA - method");
	beanB.method();
	beanC.method();
	}
	}
	class BeanB {
	public BeanB() {
	log("BeanB - constructor");
	}
	@PostConstruct
	public void postConstruct() {
	log("BeanB - postConstruct");
	}
	public void method() {
	log("BeanB - method");
	}
	}
	class BeanC {
	public BeanC() {
	log("BeanC - constructor");
	}
	@PostConstruct
	public void postConstruct() {
	log("BeanC - postConstruct");
	}
	public void method() {
	log("BeanC - method");
	}
	}
	@Import({ConfBeanA.class, ConfBeanB.class, ConfBeanC.class})
	@Configuration
	class Conf {
	}
	@Configuration
	class ConfBeanA {
	@Bean
	BeanA beanA() {
	return new BeanA();
	}
	}
	@Configuration
	class ConfBeanB {
	@Bean
	BeanB beanB() {
	return new BeanB();
	}
	}
	@Configuration
	class ConfBeanC {
	@Bean
	BeanC beanC() {
	return new BeanC();
	}
	}

view raw exc01.java hosted with ❤ by GitHub

	>> BeanA - constructor, beanB:null, beanC:null
	>> BeanC - constructor
	>> BeanC - postConstruct
	>> BeanB - constructor
	>> BeanB - postConstruct
	>> BeanA - postConstruct, beanB:org.test.context.exc.exc01.BeanB@3e77a1ed, beanC:org.test.context.exc.exc01.BeanC@3ffcd140
	>> Call BeanA
	>> BeanA - method
	>> BeanB - method
	>> BeanC - method

view raw log hosted with ❤ by GitHub

exc02

The same as exc01, but we've renamed factory method ConfBeanB#beanB() into ConfBeanB#beanC(). Spring goes over our @Import declaration to determine all possible bean definitions: ConfBeanA, ConfBeanB, ConfBeanC. There are two factory methods with the same name: ConfBeanB#beanC() and ConfBeanC#beanC(), so ConfBeanC overwrites the bean created through ConfBeanB because it creates a bean with the same name.

exc03

Similar to exc02, but this time we've renamed method ConfBeanC#beanC() into ConfBeanC#beanB(), so that we have two methods beanB, and not as it was in exc02 two methods with the name: beanC. The output is still the same, BeanB is missing. We've just changed the name of the factory method, and we already know that names do not change loading order, and we still have two beans with the same name.

exc04

Similar to exc02, but we've changed the import order for config classes from A, B, C to A, C, B. Now ConfBeanB will get scanned on end, and it overwrites the previous bean with the same name, so BeanC is missing.

exc05 

It's a modified exc02. We've set AllowBeanDefinitionOverriding to false on Application Context. Bean overwriting is disabled now, so instead of bean not found, we are getting an exception that we are trying to register two beans under the same name.

exc06

The same as exc02, there are still two factory methods: beanC. Additionally, BeanB and BeanC are implementing the common interface. Now BeanA does not inject BeanB and BeanC directly but injects a collection of beans implementing our interface. In the case of direct injection, one of the beans was missing; now both are there!

Summary

In the case of two beans with the same name, the last one wins. You cannot directly inject such overwritten beans, but you can inject a collection of such beans sharing a common interface.

Lazy Loading

exd01

We have three beans: A, B, and C, and there are no dependencies between them. BeanC is being defined through a dedicated configuration class. Nothing special here. The initialization order is as expected.

exd02

The same as exd02, but we've annotated BeanB as lazy. Spring does not load BeanB at all. There are no dependencies to that bean.

exd03

Now we've injected BeanB into BeanA. @Lazy is set on injection point and bean definition. Additionally, we have defined a method on BeanA that calls a method on BeanB: ApplicationExD03 -> beanA.method() -> beanB.method()

	class BeanA {
	@Autowired
	@Lazy
	private BeanB beanB;
	public BeanA() {
	log("BeanA - constructor: %s", beanB);
	}
	@PostConstruct
	public void postConstruct() {
	log("BeanA - postConstruct");
	}
	public void method() {
	log("BeanA - method");
	beanB.method();
	}
	}
	@Configuration
	class ConfBeanB {
	@Bean
	@Lazy
	BeanB beanB() {
	return new BeanB();
	}
	}
	class ApplicationExD03 {
	public static void main(String[] args) {
	AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
	ctx.register(Conf.class);
	ctx.refresh();
	log("Call BeanA");
	BeanA beanA = ctx.getBean(BeanA.class);
	beanA.method();
	}
	}

view raw exd03.java hosted with ❤ by GitHub

	>> BeanA - constructor: null
	>> BeanA - postConstruct
	>> BeanC - constructor: null
	>> BeanC - postConstruct
	>> Call BeanA
	>> BeanA - method
	>> BeanB - constructor
	>> BeanB - postConstruct
	>> BeanB - method

view raw gistfile1.txt hosted with ❤ by GitHub

Spring postpones the creation of BeanB until the method is being called on it, @Lazy works as expected.

exd04

Same as exd03, but @Lazy has been removed on the injection point. BeanB is not lazy anymore, @Lazy on bean definition is not enough.

exd05

Same as exd03, but @Lazy has been removed from the bean configuration. BeanB is not lazy anymore, @Lazy on bean definition is not enough.

Summary

• lazy annotation has to be provided on configuration, and all injection points, otherwise Spring eagerly initializes such beans,
• lazy beans that are not referenced (injected) are not loaded at all,
• you should not rely on @Lazy unless you are 100% sure you can control all possible injection points. Otherwise, one missing Lazy-Annotation will disable laziness on the such bean.