Bean Definitions & Metadata

Before Spring creates a single object instance, it constructs an in-memory metadata catalog describing how every bean should be built. This metadata blueprint is defined by the org.springframework.beans.factory.config.BeanDefinition interface.

Spring separates container execution into two distinct, sequential phases: the Metadata Registration Phase and the Bean Instantiation Phase. This two-phase separation is the foundational secret behind Spring Boot auto-configuration and environment interpolation.

1. 01PHASE 1 (Metadata Registration): Readers and scanners parse XML, @Component classes, and @Configuration classes. They populate the BeanDefinitionRegistry with BeanDefinition objects. No user bean constructors run during this phase.
2. 02PHASE 1.5 (Post-Processing Metadata): BeanFactoryPostProcessor implementations execute. For example, PropertySourcesPlaceholderConfigurer inspects BeanDefinition property values and resolves "${db.url}" from application.properties before any database connection is created.
3. 03PHASE 2 (Instance Creation & Wiring): During finishBeanFactoryInitialization(), the container iterates over registered BeanDefinition recipes, instantiates real Java objects, injects collaborators, runs BeanPostProcessors, and caches singletons in DefaultSingletonBeanRegistry.

Regardless of how a developer declares a component, Spring uses specialized readers to convert that input into standard BeanDefinition implementations stored in the BeanDefinitionRegistry (which is implemented directly by DefaultListableBeanFactory):

The BeanDefinitionRegistry maintains an internal Map<String, BeanDefinition> beanDefinitionMap and an ordered List<String> beanDefinitionNames. Once registered, the container processes every definition uniformly, regardless of whether it originated from XML, annotations, or Java code.

Spring Boot auto-configuration classes frequently register beans programmatically rather than relying on static annotations. You can programmatically construct and register a BeanDefinition directly using BeanDefinitionBuilder:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

import org.springframework.beans.factory.config.BeanDefinition;
import org.springframework.beans.factory.support.BeanDefinitionBuilder;
import org.springframework.beans.factory.support.DefaultListableBeanFactory;
import org.springframework.context.support.GenericApplicationContext;

public class ProgrammaticBeanRegistration {
    public static void main(String[] args) {
        var context = new GenericApplicationContext();

        // 1. Programmatically define a repository bean definition
        BeanDefinition repoDef = BeanDefinitionBuilder
            .genericBeanDefinition(InMemoryTaskRepository.class)
            .setScope(BeanDefinition.SCOPE_SINGLETON)
            .getBeanDefinition();

        // 2. Programmatically define a service bean definition with constructor reference
        BeanDefinition serviceDef = BeanDefinitionBuilder
            .genericBeanDefinition(TaskService.class)
            .setScope(BeanDefinition.SCOPE_SINGLETON)
            .addConstructorArgReference("taskRepository") // Injects bean named 'taskRepository'
            .getBeanDefinition();

        // 3. Register definitions into the BeanDefinitionRegistry
        context.registerBeanDefinition("taskRepository", repoDef);
        context.registerBeanDefinition("taskService", serviceDef);

        // 4. Refresh the context: triggers Phase 2 (Instantiation & Injection)
        context.refresh();

        TaskService service = context.getBean(TaskService.class);
        System.out.println("Service running with container-wired repository: " + service);
    }
}

This demonstrates that Spring Framework annotations like @Service and @Bean are not magical language extensions—they are simply declarative conveniences that generate BeanDefinition recipes behind the scenes.

In legacy Spring applications, registering two bean definitions with the exact same name resulted in silent bean overriding: the last definition processed would silently overwrite the previous one. This caused subtle, catastrophic production bugs when a library or starter unintentionally replaced a core application service.

Starting in Spring Boot 2.1+, bean definition overriding is disabled by default (spring.main.allow-bean-definition-overriding=false). Attempting to register two beans with identical names immediately halts startup with a fatal diagnostic exception.

1
2
3
4
5
6
7
8
9
10
11

@Configuration
public class PrimaryConfig {
    @Bean("taskRepository")
    public TaskRepository repoA() { return new InMemoryTaskRepository(); }
}

@Configuration
public class SecondaryConfig {
    @Bean("taskRepository") // Same bean name!
    public TaskRepository repoB() { return new DatabaseTaskRepository(); }
}

APPLICATION FAILED TO START
***************************
Description:
The bean 'taskRepository', defined in class path resource [SecondaryConfig.class], could not be registered. 
A bean with that name has already been defined in class path resource [PrimaryConfig.class] and overriding is disabled.

Action:
Consider renaming one of the beans or being more specific about which bean should take precedence:
  - Rename one of the @Bean methods.
  - Or use @ConditionalOnMissingBean to allow consumer overrides.