Unveiling Spring’s Core: How the refresh Method Boots the IoC Container

Preface

Recent Spring series articles received positive feedback, and many readers asked for deeper source‑code analysis. To help those who struggle with starting, getting lost in the massive codebase, or distinguishing essential parts, I will present a concise, image‑rich guide focusing on the most important Spring IoC concepts.

Want to read Spring source but don’t know where to start

Too many files, feel lost

Unclear which parts are core

Remembering details is hard

Spring source is complex; this tutorial aims to extract the essence and provide a clear reading path.

Entry Point

The top‑level Spring container interface is BeanFactory, but developers usually work with its sub‑interface ApplicationContext.

Manual initialization via XML configuration:

ClassPathXmlApplicationContext applicationContext = new ClassPathXmlApplicationContext("applicationContext.xml");
User user = (User) applicationContext.getBean("name");

Manual initialization via Java configuration class:

AnnotationConfigApplicationContext applicationContext = new AnnotationConfigApplicationContext(Config.class);
User user = (User) applicationContext.getBean("name");

Both classes ultimately invoke the refresh method, which is the real entry point for Spring container initialization.

refresh Method

The refresh method is the true entry of Spring IoC; it initializes the container.

In Spring Boot, SpringApplication.run calls refreshContext, which invokes refresh once. In Spring Cloud, BootstrapApplicationListener also triggers refresh, resulting in a second call. In Spring MVC, FrameworkServlet.initWebApplicationContext calls configureAndRefreshWebApplicationContext, which invokes refresh after checking container activation.

This explains why the refresh method may be called twice in a Spring Boot project that includes Spring Cloud.

The refresh method performs several key steps:

obtainFreshBeanFactory

invokeBeanFactoryPostProcessors

registerBeanPostProcessors

finishBeanFactoryInitialization

Parsing XML Configuration Files

obtainFreshBeanFactory

parses XML bean definitions, creates BeanDefinition objects, and registers them in the container.

The process eventually reaches AbstractBeanDefinitionReader.loadBeanDefinitions which iterates over each location (e.g., applicationContext.xml) and loads bean definitions.

Spring’s default XML tags are <import/>, <alias/>, <bean/>, and <beans/>. Custom tags such as <aop/>, <context/>, and <mvc/> are handled differently.

Generating BeanDefinition

The BeanDefinitionParserDelegate.parseBeanDefinitionElement method creates a BeanDefinition for each <bean/> tag, delegating to processBeanDefinition which ultimately instantiates a new BeanDefinition object.

Registering BeanDefinition

After parsing, the generated BeanDefinition objects are registered via BeanDefinitionReaderUtils.registerBeanDefinition, which delegates to DefaultListableBeanFactory.registerBeanDefinition. Alias handling is performed by SimpleAliasRegistry.registerAlias, allowing multiple names to refer to the same bean.

Modifying BeanDefinition

During refresh, invokeBeanFactoryPostProcessors modifies existing BeanDefinition objects. The PostProcessorRegistrationDelegate invokes both BeanDefinitionRegistryPostProcessor and BeanFactoryPostProcessor implementations, with ConfigurationClassPostProcessor handling @Configuration annotations.

Registering BeanPostProcessor

After post‑processor logic, refresh calls registerBeanPostProcessors, which registers all BeanPostProcessor implementations via PostProcessorRegistrationDelegate.registerBeanPostProcessors.

Summary

The article covered:

Spring container initialization entry point

Key steps of the refresh method

XML configuration parsing

BeanDefinition generation

BeanDefinition registration

BeanDefinition modification

BeanPostProcessor registration

Future articles will dive into bean instantiation, dependency injection, bean initialization, and BeanPostProcessor invocation.