The Container: From Main to Refresh

The invocation of SpringApplication.run() is the entry point for any Spring Boot application. However, understanding the underlying mechanics—specifically the AbstractApplicationContext and its refresh cycle—is essential for diagnosing initialization issues, optimizing startup performance, and avoiding common misconfigurations. This section dissects the core lifecycle of the Spring Framework’s application context, focusing on the precise sequence of operations that transform configuration into a fully operational container.

Introduction to ApplicationContext

The ApplicationContext is the central interface of the Spring Framework, serving as the runtime container for application components (beans). It is responsible for loading bean definitions, instantiating and wiring beans, managing their lifecycle, and providing infrastructure services such as event propagation and internationalization. In a non-web Spring Boot application, the default implementation is AnnotationConfigApplicationContext [1], which processes @Configuration classes and enables annotation-driven configuration.

This container is not a passive registry; it actively orchestrates the application’s construction through a deterministic initialization sequence known as the refresh cycle.

The Refresh Cycle

The refresh cycle is initiated by the refresh() method in AbstractApplicationContext. This method executes a strict sequence of phases, each with a specific responsibility in the construction of the runtime environment.

1. Prepare Refresh: The context validates that required environment properties are present and sets up internal state. This includes early initialization of the Environment object and checking for active profiles.

2. Obtain Fresh Bean Factory: A new instance of DefaultListableBeanFactory is created. For AnnotationConfigApplicationContext, this phase includes scanning the configuration sources (e.g., @Configuration classes) and registering @Bean method metadata as BeanDefinition objects. This is not reflection at runtime—it is metadata registration at startup.

3. Prepare Bean Factory: The bean factory is configured with essential components: the application’s class loader, type converters, and default beans such as the Environment. This step ensures the factory can resolve types and properties during subsequent phases.

4. Post Process Bean Factory: All BeanFactoryPostProcessor beans are invoked. These processors operate on the BeanDefinition registry before any beans are instantiated. A critical example is ConfigurationClassPostProcessor, which processes @Configuration classes, and PropertySourcesPlaceholderConfigurer, which resolves ${...} placeholders against the Environment [1].

5. Register Bean Post Processors: All BeanPostProcessor beans are instantiated and registered. These processors intercept bean creation and can modify instances post-construction. For example, AutowiredAnnotationBeanPostProcessor injects dependencies annotated with @Autowired. The order of registration is significant and follows precedence rules defined by Ordered or @Order.

6. Initialize Message Source and Application Event Multicaster: The MessageSource is initialized for internationalization, and the ApplicationEventMulticaster is set up to handle event publication and listener dispatch. By default, events are published synchronously unless a custom multicaster is configured.

7. Finish Bean Factory Initialization: This phase triggers the instantiation of all non-lazy singleton beans. The bean factory creates each bean, injects its dependencies, applies BeanPostProcessor callbacks (e.g., @PostConstruct), and registers the fully initialized instance in the singleton cache. This is where most of the application’s object graph is materialized.

8. Finish Refresh: The lifecycle processor is initialized, and a ContextRefreshedEvent is published. This event signals that the context is fully operational. In Spring Boot, this triggers CommandLineRunner and ApplicationRunner beans.

Understanding Bean Definitions and Instances

A fundamental distinction in Spring is between bean definitions and bean instances. A BeanDefinition is metadata—essentially a blueprint—that describes how to create a bean, including its class, scope, dependencies, and initialization method. The refresh cycle uses these definitions to instantiate actual objects. Confusing the two leads to misconceptions about when and how beans are created.

For example, in LogisticsCore, a WarehouseService may be defined via a @Bean method, but the instance is not created until finishBeanFactoryInitialization().

@Configuration
public class LogisticsConfig {
    @Bean
    public WarehouseService warehouseService(InventoryRepository repo) {
        return new WarehouseService(repo); // Instantiation occurs during refresh
    }
}

The Role of Proxies in Spring

Spring uses proxies extensively to implement features such as dependency injection, AOP, and scope management. Two proxy mechanisms are available:

• JDK Dynamic Proxy: Used when the target class implements at least one interface. The proxy implements the same interfaces and delegates calls to the target.
• CGLIB Proxy: Used when the target class does not implement interfaces or when proxyTargetClass = true is specified. CGLIB generates a subclass of the target class to intercept method calls.

By default, @Configuration classes are proxied using CGLIB to ensure that @Bean method calls within the configuration class are intercepted and return the same singleton instance, preserving the singleton contract [2]. This behavior can be disabled with @Configuration(proxyBeanMethods = false) for performance gains when full configuration semantics are not required.

@Configuration(proxyBeanMethods = false)
public class LogisticsConfig {
    // @Bean methods will not be intercepted; suitable for simple composition
}

Environment and Property Resolution

The Environment interface provides a unified abstraction for property resolution across multiple sources. During prepareRefresh(), the Environment is populated with property sources in a specific order of precedence:

1. Servlet-specific (if applicable)
2. JVM system properties (-D)
3. OS environment variables
4. @PropertySource annotations
5. Application properties (application.properties or application.yml)

Properties from higher-priority sources override those from lower ones. This hierarchy is critical in LogisticsCore, where environment variables in production may override defaults in application.properties.

For example:

# application.properties
warehouse.region=us-east-1

# Overridden by OS environment variable
# WAREHOUSE_REGION=eu-central-1

The resolution is performed by PropertySourcesPropertyResolver, which iterates through the sources in order.

Conclusion

The Spring Framework’s ApplicationContext and its refresh cycle are not abstractions to be taken for granted. They represent a deterministic, observable sequence of operations that construct the application’s runtime. Understanding the mechanics—bean definition registration, proxying strategies, and property resolution order—enables developers to build predictable, maintainable systems. In LogisticsCore, this knowledge prevents issues such as duplicate bean instantiation, incorrect property overrides, and unexpected proxy behavior. Treat the container not as magic, but as a machine with observable states and failure modes.

Sources

[1] Spring Framework Documentation: Core Technologies, Spring IO, 2023. [2] Spring Boot Reference Guide, Spring IO, 2023.