DEV Community: Silver_dev

Spring Boot Under the Hood. Part 9: Actuator, DevTools and the Rest of the Toolbox

Silver_dev — Thu, 24 Sep 2026 22:33:54 +0000

This final part gathers the tools that aren't part of the application's core runtime, yet no production project can do without: monitoring, logging, development acceleration, testing, packaging, and native compilation.

9.1. Actuator — Production-Ready Monitoring

Actuator adds ready-made HTTP/JMX endpoints for monitoring and management to your application.

9.1.1. Adding it

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

By default, only /actuator/health and /actuator/info are exposed. The rest are enabled via management.endpoints.web.exposure.include:

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env,beans

9.1.2. Built-in Endpoints

ID	What it shows
`health`	Application status (UP/DOWN)
`info`	Arbitrary info (`info.*` properties)
`metrics`	Micrometer metrics (JVM, HTTP, DataSource)
`env`	All property sources
`beans`	The full list of beans
`mappings`	All `@RequestMapping` paths
`configprops`	All `@ConfigurationProperties`
`threaddump`	JVM thread dump
`heapdump`	Heap dump (hprof)
`loggers`	View/change logging levels
`shutdown`	Graceful shutdown — removed in Boot 3.4; use `server.shutdown=graceful` instead

9.1.3. Your Own `@Endpoint`

@Component
@Endpoint(id = "featureFlags")
public class FeatureFlagsEndpoint {

    @ReadOperation
    public Map<String, Boolean> getFlags() {
        return Map.of("newCheckout", true, "darkMode", false);
    }

    @WriteOperation
    public void setFlag(@Selector String name, boolean value) {
        // set the flag
    }
}

@ReadOperation → HTTP GET (available at http://localhost:8080/actuator/featureFlags)
@WriteOperation → HTTP POST
@DeleteOperation → HTTP DELETE

9.1.4. HealthIndicators

@Component
public class ExternalServiceHealthIndicator implements HealthIndicator {
    @Override
    public Health health() {
        if (isServiceUp()) {
            return Health.up().withDetail("responseTime", "45ms").build();
        }
        return Health.down().withDetail("error", "Connection refused").build();
    }
}

Actuator collects all HealthIndicator beans and aggregates them into the overall /actuator/health status. The possible statuses are UP, DOWN, OUT_OF_SERVICE, and UNKNOWN. The overall status is the "worst" of them all.

9.1.5. Micrometer

Micrometer is a metrics facade. Actuator automatically registers a MeterRegistry and collects JVM metrics (heap, threads, GC).

@Component
public class OrderMetrics {
    private final Counter orderCounter;
    private final Timer orderTimer;

    public OrderMetrics(MeterRegistry registry) {
        this.orderCounter = Counter.builder("orders.created")
            .description("Number of created orders")
            .register(registry);
        this.orderTimer = Timer.builder("orders.processing.time")
            .register(registry);
    }

    public void onOrderCreated() { orderCounter.increment(); }
    public void recordTime(Runnable task) { orderTimer.record(task); }
}

Prometheus integration:

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

The /actuator/prometheus endpoint serves metrics in the Prometheus format.

9.1.6. Boot 4: Actuator Changes

Packages relocated: org.springframework.boot.actuate.health.Health → org.springframework.boot.health.contributor.Health.
Modularization: Actuator is split into many modules (actuator-web, actuator-jmx, actuator-sbom, etc.).
/actuator/info has been extended: process information is now included.

9.2. Logging

9.2.1. The Defaults

Spring Boot uses SLF4J as the facade and Logback as the implementation. At startup, LoggingApplicationListener (registered in spring.factories) initializes logging before the ApplicationContext is even created.

9.2.2. Configuration

System	File
Logback	`logback-spring.xml` (recommended), `logback.xml`
Log4j2	`log4j2-spring.xml`, `log4j2.xml`
JUL	`logging.properties`

The -spring variants are recommended: they support <springProfile> and <springProperty>.

<!-- logback-spring.xml -->
<configuration>
    <springProfile name="dev">
        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
            </encoder>
        </appender>
    </springProfile>

    <springProfile name="prod">
        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <file>${LOG_FILE}</file>
            <encoder>
                <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger - %msg%n</pattern>
            </encoder>
        </appender>
    </springProfile>
</configuration>

9.2.3. Levels via Properties

logging:
  level:
    root: INFO
    com.example.myapp: DEBUG
    org.springframework.web: WARN

9.2.4. Structured Logging (Boot 3.4+)

Spring Boot 3.4 added native structured logging support with no extra dependencies:

logging:
  structured:
    format:
      console: ecs   # Elastic Common Schema
      file: logstash

Formats: ecs, logstash, gelf.

9.2.5. Boot 4: Changes

The default encoding is UTF-8 for Logback, matching Log4j2.
No automatic trace/span ID correlation — you need to configure the appender manually.
Logback has been upgraded to a new version; some appenders were removed.

9.3. DevTools — Speeding Up Development

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <optional>true</optional>
</dependency>

9.3.1. Automatic Restart

DevTools uses two ClassLoaders:

ClassLoader	What it loads
Base ClassLoader	Immutable JARs (Spring, third-party libraries)
Restart ClassLoader	Your application's classes (the frequently changing ones)

When a classpath file changes, DevTools re-creates only the Restart ClassLoader while the Base one stays. That's what makes the restart several times faster than a full one.

9.3.2. LiveReload

The built-in LiveReload server automatically refreshes the browser when resources change (HTML, CSS, JS). Requires a LiveReload browser extension. Disabled via spring.devtools.livereload.enabled=false.

9.3.3. include/exclude Configuration

# META-INF/spring-devtools.properties
restart.exclude.companycommonlibs=/mycorp-common-[\\w-]+\.jar
restart.include.projectcommon=/mycorp-myproj-[\\w-]+\.jar

exclude — JARs loaded by the Base ClassLoader. include — the opposite, loaded by the Restart ClassLoader.

9.3.4. Global Settings

A .spring-boot-devtools.properties file in $HOME applies to all projects.

Important: DevTools must never make it into production. optional=true plus Maven/Gradle excludes it from the final JAR.

9.4. Testing

9.4.1. @SpringBootTest — the Full Context

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyApplicationTests {

    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    void contextLoads() {
        ResponseEntity<String> response = restTemplate.getForEntity("/api/hello", String.class);
        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
    }
}

webEnvironment:

MOCK (default) — no real server, MockMvc
RANDOM_PORT — a real server on a random port
DEFINED_PORT — on the configured port
NONE — no web environment

9.4.2. Slice Tests — Narrow Contexts

Annotation	What it loads	What to mock
`@WebMvcTest`	Only MVC: controllers, `@ControllerAdvice`, filters	Services via `@MockitoBean`
`@DataJpaTest`	Only JPA: repositories, `@Entity`, DataSource	Usually H2 in-memory
`@JsonTest`	Only Jackson/Gson	—
`@RestClientTest`	Only the REST client (`RestTemplate`, `WebClient`)	The server via MockWebServer

@WebMvcTest(UserController.class)
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean
    private UserService userService;

    @Test
    void shouldReturnUser() throws Exception {
        when(userService.findById(1L)).thenReturn(new User(1L, "Alice"));

        mockMvc.perform(get("/api/users/1"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("Alice"));
    }
}

The key advantage of slice tests: the context loads faster because only the relevant slice of auto-configuration is enabled.

9.4.3. @MockitoBean — Replacing @MockBean in Boot 4

A critical breaking change in Boot 4:

// Boot 3.x (deprecated in 3.4, removed in 4.0)
@MockBean
private UserService userService;

// Boot 4.x
import org.springframework.test.context.bean.override.mockito.MockitoBean;
@MockitoBean
private UserService userService;

@MockBean and @SpyBean are gone in Boot 4. The replacements are @MockitoBean and @MockitoSpyBean from Spring Framework.

9.4.4. ApplicationContextRunner — Testing Auto-configurations

For testing your own auto-configurations:

class MyAutoConfigurationTests {

    private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
        .withConfiguration(AutoConfigurations.of(MyServiceAutoConfiguration.class))
        .withPropertyValues("my.service.endpoint=http://localhost:9090");

    @Test
    void shouldCreateMyService() {
        contextRunner.run(context -> {
            assertThat(context).hasSingleBean(MyService.class);
        });
    }

    @Test
    void shouldBackOffWhenCustomBeanPresent() {
        contextRunner
            .withUserConfiguration(CustomConfig.class)
            .run(context -> {
                assertThat(context).hasSingleBean(MyService.class);
                assertThat(context.getBean(MyService.class)).isInstanceOf(CustomMyService.class);
            });
    }
}

ApplicationContextRunner lets you test auto-configuration conditions in isolation, without loading the whole application.

9.5. Build and Packaging

9.5.1. spring-boot-maven-plugin

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

The repackage goal creates an executable JAR (a fat jar):

mvn clean package
java -jar target/myapp-0.0.1-SNAPSHOT.jar

9.5.2. Layered JAR

Since Boot 2.3, the JAR can be split into layers for efficient Docker caching:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <layers>
            <enabled>true</enabled>
        </layers>
    </configuration>
</plugin>

Layers (from rarely changing to frequently changing):

dependencies — stable dependencies
spring-boot-loader — the loader
snapshot-dependencies — snapshots
application — your code

Dockerfile:

FROM eclipse-temurin:21-jre AS builder
WORKDIR /app
COPY target/myapp-*.jar app.jar
RUN java -Djarmode=tools -jar app.jar extract --layers --launcher

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=builder /app/dependencies/ ./
COPY --from=builder /app/spring-boot-loader/ ./
COPY --from=builder /app/snapshot-dependencies/ ./
COPY --from=builder /app/application/ ./
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

9.5.3. JarLauncher

JarLauncher is the fat jar's entry point. It lives in spring-boot-loader and is responsible for:

Reading MANIFEST.MF (Main-Class: org.springframework.boot.loader.launch.JarLauncher)
Building a URLClassLoader with all the nested JARs
Delegating to the Start-Class (your main class)

There's also WarLauncher and PropertiesLauncher (for external configurations).

9.5.4. Buildpacks

mvn spring-boot:build-image

Spring Boot uses Paketo Buildpacks to create an OCI image without a Dockerfile:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <image>
            <name>myregistry/myapp:${project.version}</name>
        </image>
    </configuration>
</plugin>

9.5.5. Boot 4: Changes

Starters renamed: spring-boot-starter-web → spring-boot-starter-webmvc.
Undertow removed (incompatible with Servlet 6.1).
spring-boot-loader remains, but the packages have been relocated.

9.6. AOT and GraalVM Native Image (an Overview)

9.6.1. What Is AOT

Ahead-of-Time — processing the application at build time rather than at runtime. Spring Boot 3+ performs AOT processing that:

Scans all @Configuration, @Bean, @Component classes.
Generates Java code for bean registration (instead of reflection).
Registers RuntimeHints — hints for GraalVM.

Why: GraalVM Native Image compiles Java into a native executable. Reflection, dynamic proxies, and resource loading only work in a native image if you declare them at build time.

9.6.2. RuntimeHintsRegistrar

public class MyRuntimeHints implements RuntimeHintsRegistrar {
    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        hints.reflection().registerType(MyDto.class, MemberCategory.values());
        hints.resources().registerPattern("my-config/*.json");
    }
}

Registration:

@ImportRuntimeHints(MyRuntimeHints.class)
@Configuration
public class MyConfig { }

9.6.3. @RegisterReflectionForBinding — a Shortcut

@Configuration
@RegisterReflectionForBinding({User.class, UserDto.class})
public class JacksonConfig { }

The annotation registers reflection hints for DTOs that get serialized by Jackson.

9.6.4. Building a Native Image

mvn -Pnative native:compile

The result is a native executable:

./target/myapp

Advantages:

Instant startup (milliseconds instead of seconds)
Lower memory consumption
Smaller image size

Limitations:

No dynamic class loading
No JIT (lower peak performance)
Longer builds
Not all libraries are supported

9.6.5. Boot 4: AOT by Default

In Boot 4, AOT processing is more aggressive: reflection-free by default for most scenarios. BeanRegistrar (introduced in Spring Framework 7) is the primary way to register beans for AOT, replacing reflection-based @Bean methods.

9.7. Summary Table: Boot 3 vs Boot 4

Aspect	Spring Boot 3.x	Spring Boot 4.x
Actuator packages	`org.springframework.boot.actuate.health`	`org.springframework.boot.health.contributor`
Actuator modules	A single `spring-boot-actuator`	Many modules (web, jmx, sbom...)
Default logging	Logback, charset depends on the OS	Logback, UTF-8 always
Structured logging	Introduced in 3.4	Fully integrated
Test annotations	`@MockBean`, `@SpyBean`	Removed; replaced by `@MockitoBean`, `@MockitoSpyBean`
Starters	`spring-boot-starter-web`	`spring-boot-starter-webmvc`
AOT	Opt-in, `-Pnative`	More aggressive, reflection-free
Buildpacks	Supported	Supported, improved
Layered JAR	Present	Present, improved

9.8. Key Takeaways

Actuator — not just /health. Custom endpoints via @Endpoint + @ReadOperation/@WriteOperation. HealthIndicator — for checking external services. Micrometer — for metrics.
Logging is initialized before the ApplicationContext. Use logback-spring.xml, not logback.xml. Since Boot 3.4 — structured logging out of the box.
DevTools uses two ClassLoaders: Base (stable JARs) and Restart (your code). It restarts only the latter.
Testing: @SpringBootTest — the full context; slice tests — narrow contexts. ApplicationContextRunner — for testing auto-configurations.
@MockBean → @MockitoBean — a critical breaking change in Boot 4.
Layered JAR — splitting into layers for Docker caching. JarLauncher — the fat jar's entry point.
Buildpacks — an OCI image without a Dockerfile: mvn spring-boot:build-image.
AOT — build-time processing for GraalVM. @RegisterReflectionForBinding — for DTOs. Native image: instant startup, but with limitations.

The End of the Series

Spring Boot Under the Hood. Part 8: Graceful Exit — How Spring Boot Starts and Stops

Silver_dev — Thu, 24 Sep 2026 20:46:16 +0000

In Part 1, we left off where SpringApplication.run() calls callRunners() and publishes ApplicationReadyEvent. Now let's look at those steps in detail — plus the complete application shutdown cycle, from the JVM shutdown hook down to @PreDestroy.

8.1. ApplicationRunner and CommandLineRunner — the Entry Point into the "Ready" Application

Once the context is fully up (all beans created, Tomcat running), Spring Boot invokes the beans that implement ApplicationRunner or CommandLineRunner.

@FunctionalInterface
public interface ApplicationRunner {
    void run(ApplicationArguments args) throws Exception;
}

@FunctionalInterface
public interface CommandLineRunner {
    void run(String... args) throws Exception;
}

The key difference is the argument format:

Interface	Parameter	Example access
`CommandLineRunner`	`String[]` (raw)	`args[0]` → `--server.port=9090`
`ApplicationRunner`	`ApplicationArguments`	`args.getOptionNames()` → `[server.port]`

ApplicationArguments is an already-parsed object that Spring Boot builds from the String[]:

DefaultApplicationArguments args = new DefaultApplicationArguments(sourceArgs);
// args.getOptionNames() → Set<String>
// args.getOptionValues("server.port") → List<String>
// args.getSourceArgs() → String[]
// args.getNonOptionArgs() → List<String>

8.2. The Order in Which Runners Are Invoked

Inside SpringApplication.callRunners():

private void callRunners(ApplicationContext context, ApplicationArguments args) {
    List<Object> runners = new ArrayList<>();
    runners.addAll(context.getBeansOfType(ApplicationRunner.class).values());
    runners.addAll(context.getBeansOfType(CommandLineRunner.class).values());
    AnnotationAwareOrderComparator.sort(runners);
    for (Object runner : new LinkedHashSet<>(runners)) {
        if (runner instanceof ApplicationRunner applicationRunner) {
            callRunner(applicationRunner, args);
        }
        if (runner instanceof CommandLineRunner commandLineRunner) {
            callRunner(commandLineRunner, args);
        }
    }
}

Important details:

Both types are collected into a single list.
Sorting is done via AnnotationAwareOrderComparator — by @Order / Ordered.
@Order only affects the order in which run() is invoked — not the order in which the beans are created.
If @Order isn't specified, the order is undefined.

8.3. The Rule: Runners Instead of @PostConstruct

The key Spring Boot rule: tasks that should run at application startup (after the context is fully initialized) should be implemented via ApplicationRunner or CommandLineRunner — not via @PostConstruct.

Why:

@PostConstruct runs during bean initialization, when not all beans are ready yet.
Runners are invoked after the entire context has been refreshed, all beans are created, and the web server is running.
Runners get access to ApplicationArguments.

8.4. Graceful Shutdown

Since Spring Boot 2.3, graceful shutdown is built in.

What happens:

The application receives a SIGTERM signal (e.g., from Kubernetes).
The JVM shutdown hook initiates context.close().
The first phase — stop accepting new requests.
Existing requests get a grace period to finish.
Once all requests are done — the beans are destroyed.

Configuration:

server:
  shutdown: graceful
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

server.shutdown can be graceful or immediate (the default). timeout-per-shutdown-phase is the maximum time to wait for requests to complete (30 seconds by default).

Behavior by server:

Server	How it rejects new requests
Tomcat	At the network level (stops accepting connections)
Jetty	At the network level
Reactor Netty	At the network level
Undertow	Accepts the connection but responds with `503 Service Unavailable`

Important: graceful shutdown only works when a proper SIGTERM is received. If you stop the application from your IDE (the Stop button), the IDE may send SIGKILL, and graceful shutdown won't kick in.

8.5. WebServerGracefulShutdownLifecycle — the Implementation

As we saw in Part 7, when the WebServer is created, two lifecycle beans are registered:

getBeanFactory().registerSingleton("webServerGracefulShutdown", 
    new WebServerGracefulShutdownLifecycle(this.webServer));
getBeanFactory().registerSingleton("webServerStartStop", 
    new WebServerStartStopLifecycle(this, this.webServer));

WebServerGracefulShutdownLifecycle implements SmartLifecycle

class WebServerGracefulShutdownLifecycle implements SmartLifecycle {
    private final WebServer webServer;
    private volatile boolean running;

    @Override
    public void start() {
        this.running = true;
    }

    @Override
    public void stop(Runnable callback) {
        this.running = false;
        this.webServer.shutDownGracefully((result) -> callback.run());
    }

    @Override
    public int getPhase() {
        return Integer.MAX_VALUE;  // ← the highest phase
    }
}

Key point: getPhase() = Integer.MAX_VALUE. During shutdown, SmartLifecycle beans are stopped in descending phase order, so the web server's graceful shutdown happens first — before the beans that may still be processing requests (DataSource, services, etc.) are destroyed.

8.6. SmartLifecycle and LifecycleProcessor — the Start/Stop Order

SmartLifecycle extends Lifecycle and Phased:

public interface SmartLifecycle extends Lifecycle, Phased {
    boolean isAutoStartup();
    void stop(Runnable callback);

    @Override
    default int getPhase() {
        return 0;
    }
}

The ordering rules:

Phase	Startup	Shutdown
`Integer.MIN_VALUE`	First	Last
`0` (default)	Middle	Middle
`Integer.MAX_VALUE`	Last	First

At startup (onRefresh()): phases are sorted in ascending order — MIN_VALUE starts first, MAX_VALUE last.

At shutdown (onClose()): phases are sorted in descending order — MAX_VALUE stops first, MIN_VALUE last.

This is driven by the DefaultLifecycleProcessor:

public class DefaultLifecycleProcessor implements LifecycleProcessor, BeanFactoryAware {
    private long timeoutPerShutdownPhase = 30000;  // 30 seconds

    @Override
    public void onRefresh() {
        startBeans(true);  // all SmartLifecycle beans with isAutoStartup() == true
    }

    @Override
    public void onClose() {
        stopBeans();       // all running Lifecycle beans
    }
}

timeoutPerShutdownPhase is the maximum wait time for a single phase. If a bean hasn't finished its stop() within that time — Spring moves on without waiting for it.

8.7. The JVM Shutdown Hook — How the JVM Knows It's Time to Stop

SpringApplication.refreshContext() automatically registers a shutdown hook:

private void refreshContext(ConfigurableApplicationContext context) {
    if (this.registerShutdownHook) {
        try {
            context.registerShutdownHook();
        } catch (AccessControlException ex) {
            // Not allowed in some environments
        }
    }
    refresh(context);
}

registerShutdownHook is true by default. It can be disabled via SpringApplication.setRegisterShutdownHook(false).

Inside AbstractApplicationContext:

public void registerShutdownHook() {
    if (this.shutdownHook == null) {
        this.shutdownHook = new Thread(SHUTDOWN_HOOK_THREAD_NAME) {
            @Override
            public void run() {
                synchronized (startupShutdownMonitor) {
                    doClose();
                }
            }
        };
        Runtime.getRuntime().addShutdownHook(this.shutdownHook);
    }
}

The shutdown chain:

SIGTERM from the OS / Ctrl+C / kill <pid>
    │
    ▼
JVM Shutdown Hook (Thread "SpringContextShutdownHook")
    │
    ▼
AbstractApplicationContext.doClose()
    │
    ├─ 1. LifecycleProcessor.onClose()
    │       └─ SmartLifecycle.stop() — descending phase order
    │             ├─ WebServerGracefulShutdownLifecycle (MAX_VALUE) — graceful shutdown
    │             ├─ WebServerStartStopLifecycle (MAX-1) — tomcat.stop()
    │             └─ ... custom SmartLifecycle beans
    │
    ├─ 2. destroyBeans()
    │       └─ for each singleton:
    │             ├─ @PreDestroy (DestructionAwareBeanPostProcessor)
    │             ├─ DisposableBean.destroy()
    │             └─ @Bean(destroyMethod) / AutoCloseable.close()
    │
    ├─ 3. closeBeanFactory()
    │
    └─ 4. active.set(false)

8.8. Closing the Context Manually

If you need to close the context programmatically (e.g., in tests or a CLI application):

ConfigurableApplicationContext context = SpringApplication.run(MyApp.class, args);
// ... work
context.close();  // → doClose()

Or via SpringApplication.exit():

int exitCode = SpringApplication.exit(context, () -> 0);
System.exit(exitCode);

8.9. Spring Boot 3 vs Spring Boot 4 — the Differences

Aspect	Spring Boot 3.x	Spring Boot 4.x
Graceful shutdown	Built in, `server.shutdown=graceful`	Built in, enabled by default for all embedded servers
Undertow	Supported	Removed (incompatible with Servlet 6.1)
Jetty graceful shutdown	`StatisticsHandler`	`GracefulHandler` (changed in 4.2)
`WebServerGracefulShutdownLifecycle`	`org.springframework.boot.web.server`	Modular structure, packages relocated
`ApplicationRunner` / `CommandLineRunner`	Unchanged	Unchanged
`SmartLifecycle` / `LifecycleProcessor`	Unchanged	Unchanged
JVM shutdown hook	`true` by default	`true` by default
Deadlock fix	—	Spring Framework 7.0.4: fixed a deadlock with concurrent shutdown hooks (issue #36260)

The key change in Boot 4: graceful shutdown is enabled by default for all embedded servers. This means that on SIGTERM, the application automatically stops accepting new requests and waits for the existing ones to complete — with zero configuration.

8.10. Key Takeaways

ApplicationRunner vs CommandLineRunner — the only difference is the argument format (ApplicationArguments vs String[]). ApplicationRunner is preferred.
Runner ordering — via @Order / Ordered. Runners are invoked after the context is fully initialized but before ApplicationReadyEvent.
@PostConstruct ≠ runner. "At application startup" tasks belong in runners.
Graceful shutdown — server.shutdown=graceful + spring.lifecycle.timeout-per-shutdown-phase. Enabled by default in Boot 4.
SmartLifecycle ordering: startup in ascending phase, shutdown in descending. WebServerGracefulShutdownLifecycle has phase = MAX_VALUE, so it stops first.
The JVM shutdown hook is registered automatically (registerShutdownHook = true). It's what triggers context.close() on SIGTERM / Ctrl+C.
The shutdown chain: shutdown hook → doClose() → LifecycleProcessor.onClose() → destroyBeans() → @PreDestroy → DisposableBean.destroy().
Boot 4: graceful shutdown by default, Undertow removed, the shutdown-hook deadlock fixed.

Spring Boot Under the Hood. Part 7: From Embedded Tomcat to Your @RestController

Silver_dev — Thu, 24 Sep 2026 19:17:02 +0000

We've reached the point where refresh() calls onRefresh() on the context. For web applications, onRefresh() is where the embedded web server is created and started — we saw this moment on the diagram in Part 6. Let's break down how Spring Boot picks the server, creates the DispatcherServlet, and handles errors.

7.1. Servlet vs Reactive — Two Parallel Worlds

Spring Boot supports two stacks:

Stack	WebApplicationType	Default server	Context
Spring MVC	`SERVLET`	Tomcat	`AnnotationConfigServletWebServerApplicationContext`
Spring WebFlux	`REACTIVE`	Reactor Netty	`AnnotationConfigReactiveWebServerApplicationContext`

The choice happens in the SpringApplication constructor via deduceWebApplicationType(). If DispatcherServlet (Spring MVC) is on the classpath → SERVLET. If DispatcherHandler (WebFlux) is present without MVC → REACTIVE.

Important: if both are on the classpath, SERVLET wins. Spring Boot gives MVC priority as the "older" stack.

7.2. Web Server Auto-configuration — ServletWebServerFactoryAutoConfiguration

The main class for the Servlet stack:

@AutoConfiguration
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)
@ConditionalOnClass(ServletRequest.class)
@ConditionalOnWebApplication(type = Type.SERVLET)
@EnableConfigurationProperties(ServerProperties.class)
@Import({ 
    ServletWebServerFactoryAutoConfiguration.BeanPostProcessorsRegistrar.class,
    ServletWebServerFactoryConfiguration.EmbeddedTomcat.class,
    ServletWebServerFactoryConfiguration.EmbeddedJetty.class,
    ServletWebServerFactoryConfiguration.EmbeddedUndertow.class 
})
public class ServletWebServerFactoryAutoConfiguration {

    @Bean
    public ServletWebServerFactoryCustomizer servletWebServerFactoryCustomizer(
            ServerProperties serverProperties) {
        return new ServletWebServerFactoryCustomizer(serverProperties);
    }
}

Key points:

@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE) — the server is created before most other auto-configurations.
@Import pulls in three nested configurations — for Tomcat, Jetty, and Undertow. Each one is activated via @ConditionalOnClass.

7.2.1. EmbeddedTomcat — Picking the Server

@Configuration(proxyBeanMethods = false)
@ConditionalOnClass({ Servlet.class, Tomcat.class, UpgradeProtocol.class })
@ConditionalOnMissingBean(value = ServletWebServerFactory.class, 
    search = SearchStrategy.CURRENT)
static class EmbeddedTomcat {

    @Bean
    TomcatServletWebServerFactory tomcatServletWebServerFactory(
            ObjectProvider<TomcatConnectorCustomizer> connectorCustomizers,
            ObjectProvider<TomcatContextCustomizer> contextCustomizers,
            ObjectProvider<TomcatProtocolHandlerCustomizer<?>> protocolHandlerCustomizers) {
        // ...
        return factory;
    }
}

The selection logic:

If Tomcat.class is on the classpath and there's no custom ServletWebServerFactory — a TomcatServletWebServerFactory is created.
If you swap Tomcat for spring-boot-starter-jetty — @ConditionalOnClass(Tomcat.class) fails, and EmbeddedJetty kicks in.
If you declare your own ServletWebServerFactory — @ConditionalOnMissingBean backs off, and your factory wins.

7.3. ServletWebServerApplicationContext.onRefresh() — Creating the Server

The entry point is onRefresh() in ServletWebServerApplicationContext:

@Override
protected void onRefresh() {
    super.onRefresh();
    try {
        createWebServer();
    } catch (Throwable ex) {
        throw new ApplicationContextException("Unable to start web server", ex);
    }
}

createWebServer():

private void createWebServer() {
    WebServer webServer = this.webServer;
    ServletContext servletContext = getServletContext();
    if (webServer == null && servletContext == null) {
        StartupStep createWebServer = getApplicationStartup()
            .start("spring.boot.webserver.create");
        ServletWebServerFactory factory = getWebServerFactory();
        this.webServer = factory.getWebServer(getSelfInitializer());
        createWebServer.tag("factory", factory.getClass().toString());
        getBeanFactory().registerSingleton("webServerGracefulShutdown", 
            new WebServerGracefulShutdownLifecycle(this.webServer));
        getBeanFactory().registerSingleton("webServerStartStop", 
            new WebServerStartStopLifecycle(this, this.webServer));
    } else if (servletContext != null) {
        // ... embedded container
    }
}

Key steps:

getWebServerFactory() — fetches the ServletWebServerFactory from the context.
factory.getWebServer(getSelfInitializer()) — creates the WebServer and passes a callback for initializing the ServletContext.
Two lifecycle beans are registered:
- webServerStartStop — starts/stops the server
- webServerGracefulShutdown — graceful shutdown

7.3.1. getSelfInitializer() — the Bridge to ServletContextInitializer

private org.springframework.boot.web.servlet.ServletContextInitializer getSelfInitializer() {
    return this::selfInitialize;
}

private void selfInitialize(ServletContext servletContext) throws ServletException {
    prepareWebApplicationContext(servletContext);
    registerApplicationScope(servletContext);
    WebApplicationContextUtils.registerEnvironmentBeans(getBeanFactory(), servletContext);
    for (ServletContextInitializer beans : getServletContextInitializerBeans()) {
        beans.onStartup(servletContext);
    }
}

ServletContextInitializer is a Spring Boot SPI interface:

@FunctionalInterface
public interface ServletContextInitializer {
    void onStartup(ServletContext servletContext) throws ServletException;
}

Every bean implementing ServletContextInitializer is invoked when the server starts. This is exactly how the DispatcherServlet, filters, and listeners get registered.

7.3.2. ServletContextInitializerBeans — Collecting All the Initializers

public class ServletContextInitializerBeans 
        extends AbstractCollection<ServletContextInitializer> {

    public ServletContextInitializerBeans(ListableBeanFactory beanFactory, 
            Class<? extends ServletContextInitializer>... initializerTypes) {
        // 1. Collects all ServletContextInitializer beans
        // 2. Collects all ServletRegistrationBean, FilterRegistrationBean,
        //    ServletListenerRegistrationBean instances
        // 3. Sorts them via @Order / Ordered
    }
}

What ends up in here:

DispatcherServletRegistrationBean — registers the DispatcherServlet (from DispatcherServletAutoConfiguration)
Custom Filters (Spring Security, etc.)
@WebServlet, @WebFilter, @WebListener (with @ServletComponentScan)

7.4. WebServerStartStopLifecycle — Starting Tomcat

Once the WebServer is created, a lifecycle bean is registered:

class WebServerStartStopLifecycle implements SmartLifecycle {
    private final ServletWebServerApplicationContext applicationContext;
    private final WebServer webServer;
    private volatile boolean running;

    @Override
    public void start() {
        this.webServer.start();
        this.running = true;
        this.applicationContext.publishEvent(
            new ServletWebServerInitializedEvent(this.webServer, this.applicationContext));
    }

    @Override
    public void stop() {
        this.webServer.stop();
        this.running = false;
    }

    @Override
    public int getPhase() {
        return Integer.MAX_VALUE - 1;  // starts almost last
    }
}

SmartLifecycle callbacks fire in finishRefresh() → lifecycleProcessor.onRefresh(). getPhase() = Integer.MAX_VALUE - 1 means the server starts after all the other lifecycle beans.

The order:

refresh() → finishRefresh() → lifecycleProcessor.onRefresh()
WebServerStartStopLifecycle.start() → tomcat.start()
ServletWebServerInitializedEvent is published

7.5. DispatcherServletAutoConfiguration — Creating the DispatcherServlet

@AutoConfiguration(after = ServletWebServerFactoryAutoConfiguration.class)
@ConditionalOnClass(DispatcherServlet.class)
@AutoConfigureAfter(ServletWebServerFactoryAutoConfiguration.class)
public class DispatcherServletAutoConfiguration {

    @Configuration(proxyBeanMethods = false)
    @ConditionalOnClass(DispatcherServlet.class)
    @EnableConfigurationProperties(WebMvcProperties.class)
    protected static class DispatcherServletConfiguration {

        @Bean(name = DispatcherServletAutoConfiguration.DEFAULT_DISPATCHER_SERVLET_BEAN_NAME)
        public DispatcherServlet dispatcherServlet(WebMvcProperties webMvcProperties) {
            DispatcherServlet dispatcherServlet = new DispatcherServlet();
            dispatcherServlet.setDispatchOptionsRequest(
                webMvcProperties.isDispatchOptionsRequest());
            dispatcherServlet.setDispatchTraceRequest(
                webMvcProperties.isDispatchTraceRequest());
            // ...
            return dispatcherServlet;
        }

        @Bean
        public DispatcherServletRegistrationBean dispatcherServletRegistration(
                DispatcherServlet dispatcherServlet, WebMvcProperties webMvcProperties,
                ObjectProvider<MultipartConfigElement> multipartConfig) {
            DispatcherServletRegistrationBean registration = 
                new DispatcherServletRegistrationBean(dispatcherServlet, 
                    webMvcProperties.getServlet().getPath());
            registration.setName(DEFAULT_DISPATCHER_SERVLET_BEAN_NAME);
            registration.setLoadOnStartup(webMvcProperties.getServlet().getLoadOnStartup());
            multipartConfig.ifAvailable(registration::setMultipartConfig);
            return registration;
        }
    }
}

Two key beans:

dispatcherServlet — the DispatcherServlet itself.
dispatcherServletRegistration — a DispatcherServletRegistrationBean, which implements ServletContextInitializer. When the server starts, it registers the DispatcherServlet in the ServletContext.

Ordering: @AutoConfigureAfter(ServletWebServerFactoryAutoConfiguration.class) guarantees that the DispatcherServlet is created after the ServletWebServerFactory has been defined.

7.6. WebMvcAutoConfiguration — Wiring Up Spring MVC

@AutoConfiguration(after = { DispatcherServletAutoConfiguration.class, 
    TaskExecutionAutoConfiguration.class, ValidationAutoConfiguration.class })
@ConditionalOnWebApplication(type = Type.SERVLET)
@ConditionalOnClass({ Servlet.class, DispatcherServlet.class, WebMvcConfigurer.class })
@ConditionalOnMissingBean(WebMvcConfigurationSupport.class)
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE + 10)
@ImportRuntimeHints(WebResourcesRuntimeHints.class)
public class WebMvcAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public InternalResourceViewResolver defaultViewResolver() { ... }

    @Bean
    @ConditionalOnMissingBean
    public RequestMappingHandlerAdapter requestMappingHandlerAdapter(...) { ... }

    @Bean
    @ConditionalOnMissingBean
    public RequestMappingHandlerMapping requestMappingHandlerMapping(...) { ... }

    @Bean
    @ConditionalOnMissingBean
    public HttpMessageConverters messageConverters(...) { ... }
}

@ConditionalOnMissingBean(WebMvcConfigurationSupport.class) — the key point. If you add @EnableWebMvc, Spring Boot backs off, and the entire MVC auto-configuration is disabled. You get vanilla Spring MVC without Boot's customizations.

What WebMvcAutoConfiguration creates:

RequestMappingHandlerMapping — mapping URLs → controller methods
RequestMappingHandlerAdapter — invoking controller methods
HttpMessageConverters — Jackson, String, ByteArray, etc.
InternalResourceViewResolver — for JSPs
MessageSource — i18n
Validator — JSR-380

7.7. ErrorMvcAutoConfiguration — Error Handling

/error is not part of Spring MVC. It's a Spring Boot add-on.

@AutoConfiguration
@ConditionalOnWebApplication(type = Type.SERVLET)
@ConditionalOnClass({ Servlet.class, DispatcherServlet.class })
@AutoConfigureBefore(WebMvcAutoConfiguration.class)
@EnableConfigurationProperties({ ServerProperties.class, WebMvcProperties.class })
public class ErrorMvcAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean(value = ErrorAttributes.class, search = SearchStrategy.CURRENT)
    public DefaultErrorAttributes errorAttributes() {
        return new DefaultErrorAttributes();
    }

    @Bean
    @ConditionalOnMissingBean(value = ErrorController.class, search = SearchStrategy.CURRENT)
    public BasicErrorController basicErrorController(ErrorAttributes errorAttributes,
            ObjectProvider<ErrorViewResolver> errorViewResolvers) {
        return new BasicErrorController(errorAttributes, this.serverProperties.getError(),
            errorViewResolvers.orderedStream().toList());
    }

    @Bean
    public ErrorPageCustomizer errorPageCustomizer(DispatcherServletPath dispatcherServletPath) {
        return new ErrorPageCustomizer(this.serverProperties, dispatcherServletPath);
    }
}

7.7.1. BasicErrorController — the /error Handler

@Controller
@RequestMapping("${server.error.path:${error.path:/error}}")
public class BasicErrorController extends AbstractErrorController {

    @RequestMapping(produces = MediaType.TEXT_HTML_VALUE)
    public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) {
        HttpStatus status = getStatus(request);
        Map<String, Object> model = Collections.unmodifiableMap(
            getErrorAttributes(request, getErrorAttributeOptions(request, MediaType.TEXT_HTML)));
        response.setStatus(status.value());
        ModelAndView modelAndView = resolveErrorView(request, response, status, model);
        return (modelAndView != null) ? modelAndView : new ModelAndView("error", model);
    }

    @RequestMapping
    public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {
        HttpStatus status = getStatus(request);
        if (status == HttpStatus.NO_CONTENT) {
            return new ResponseEntity<>(status);
        }
        Map<String, Object> body = getErrorAttributes(request, 
            getErrorAttributeOptions(request, MediaType.ALL));
        return new ResponseEntity<>(body, status);
    }
}

What BasicErrorController does:

Handles /error
If Accept: text/html → renders an HTML page (the Whitelabel Error Page)
If Accept: application/json → returns JSON

7.7.2. DefaultErrorAttributes — the Error Model

public class DefaultErrorAttributes implements ErrorAttributes {

    @Override
    public Map<String, Object> getErrorAttributes(WebRequest webRequest, 
            ErrorAttributeOptions options) {
        Map<String, Object> errorAttributes = new LinkedHashMap<>();
        errorAttributes.put("timestamp", new Date());
        addStatus(errorAttributes, webRequest);
        addErrorDetails(errorAttributes, webRequest, options);
        addPath(errorAttributes, webRequest, options);
        return errorAttributes;
    }
}

The standard JSON:

{
    "timestamp": "2026-09-23T12:00:00.000+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "message": "...",
    "path": "/api/order"
}

7.7.3. ErrorPageCustomizer — Registering the Error Page

private static class ErrorPageCustomizer implements ErrorPageRegistrar, Ordered {

    @Override
    public void registerErrorPages(ErrorPageRegistry errorPageRegistry) {
        ErrorPage errorPage = new ErrorPage(
            this.dispatcherServletPath.getRelativePath(this.properties.getError().getPath()));
        errorPageRegistry.addErrorPages(errorPage);
    }
}

It registers /error as the error page in Tomcat. When Tomcat catches an unhandled exception (or a 404/405), it forwards the request to /error, where BasicErrorController produces the response.

The chain:

Controller → DispatcherServlet → HandlerExceptionResolver → not handled
    → Tomcat → forward to /error → BasicErrorController

7.8. Server Customization — ServerProperties

All the server.* settings are read into ServerProperties:

@ConfigurationProperties(prefix = "server", ignoreUnknownFields = true)
public class ServerProperties {
    private Integer port;
    private InetAddress address;
    private String contextPath;
    private final Servlet servlet = new Servlet();
    private final Tomcat tomcat = new Tomcat();
    private final Jetty jetty = new Jetty();
    // ...
}

Key settings:

Property	What it does
`server.port`	the port (8080 by default)
`server.address`	the address to listen on
`server.servlet.context-path`	the application's root path
`server.servlet.session.timeout`	session timeout
`server.tomcat.threads.max`	Tomcat's max threads
`server.tomcat.threads.min-spare`	min spare threads
`server.shutdown=graceful`	graceful shutdown
`spring.lifecycle.timeout-per-shutdown-phase`	graceful shutdown timeout

7.8.1. ServletWebServerFactoryCustomizer — Applying the Properties

public class ServletWebServerFactoryCustomizer 
        implements WebServerFactoryCustomizer<ConfigurableServletWebServerFactory>, Ordered {

    private final ServerProperties serverProperties;

    @Override
    public void customize(ConfigurableServletWebServerFactory factory) {
        PropertyMapper map = PropertyMapper.get().alwaysApplyingWhenNonNull();
        map.from(this.serverProperties::getPort).to(factory::setPort);
        map.from(this.serverProperties::getAddress).to(factory::setAddress);
        map.from(this.serverProperties.getServlet()::getContextPath).to(factory::setContextPath);
        map.from(this.serverProperties.getServlet()::getSession).to(factory::setSession);
        map.from(this.serverProperties::getSsl).to(factory::setSsl);
        map.from(this.serverProperties::getCompression).to(factory::setCompression);
        map.from(this.serverProperties::getHttp2).to(factory::setHttp2);
        map.from(this.serverProperties::getError).to(factory::setErrorPages);
    }

    @Override
    public int getOrder() {
        return 0;  // before user-defined customizers
    }
}

@Order(0) — auto-configured customizers run before user-defined ones. If you want to override a setting, declare your own WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> — it will run later and overwrite the value.

7.8.2. Your Own WebServerFactoryCustomizer

@Component
public class MyTomcatCustomizer 
        implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {

    @Override
    public void customize(TomcatServletWebServerFactory factory) {
        factory.addConnectorCustomizers(connector -> {
            connector.setProperty("maxKeepAliveRequests", "100");
        });
    }
}

7.9. The Reactive Stack — WebFlux and Netty

7.9.1. ReactiveWebServerFactoryAutoConfiguration

@AutoConfiguration
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)
@ConditionalOnClass(ReactiveHttpInputMessage.class)
@ConditionalOnWebApplication(type = Type.REACTIVE)
@EnableConfigurationProperties(ServerProperties.class)
@Import({ 
    ReactiveWebServerFactoryAutoConfiguration.BeanPostProcessorsRegistrar.class,
    ReactiveWebServerFactoryConfiguration.EmbeddedTomcat.class,
    ReactiveWebServerFactoryConfiguration.EmbeddedJetty.class,
    ReactiveWebServerFactoryConfiguration.EmbeddedUndertow.class,
    ReactiveWebServerFactoryConfiguration.EmbeddedNetty.class 
})
public class ReactiveWebServerFactoryAutoConfiguration {

    @Bean
    public ReactiveWebServerFactoryCustomizer reactiveWebServerFactoryCustomizer(
            ServerProperties serverProperties) {
        return new ReactiveWebServerFactoryCustomizer(serverProperties);
    }
}

EmbeddedNetty is activated via @ConditionalOnClass({ HttpServer.class, ... }) and creates a NettyReactiveWebServerFactory.

7.9.2. NettyReactiveWebServerFactory

public class NettyReactiveWebServerFactory extends AbstractReactiveWebServerFactory {

    @Override
    public WebServer getWebServer(HttpHandler httpHandler) {
        HttpServer httpServer = createHttpServer();
        // ... configuration
        return new NettyWebServer(httpServer, handler, 
            getRouteProvider(), this::getServerShutdownTimeout);
    }
}

The HttpHandler is built by WebHttpHandlerBuilder, which wires up WebFlux's DispatcherHandler. No Servlet API — Netty talks to the HttpHandler directly.

7.9.3. Key Differences from Servlet

Aspect	Servlet (Tomcat)	Reactive (Netty)
Model	Thread-per-request	Event loop
API	`ServletContext`, `HttpServletRequest`	`ServerHttpRequest`, `ServerHttpResponse`
Handler	`DispatcherServlet`	`DispatcherHandler`
Errors	`/error` + `BasicErrorController`	`DefaultErrorWebExceptionHandler`
Lifecycle	`WebServerStartStopLifecycle`	`NettyWebServer`

7.10. Spring Boot 3 vs Spring Boot 4 — Key Differences

7.10.1. Modularization

The biggest change. In Boot 3, everything lives in spring-boot-autoconfigure. In Boot 4, there are 47 modules:

Boot 3	Boot 4
`spring-boot-autoconfigure` (everything)	`spring-boot-webmvc` (MVC)
	`spring-boot-webflux` (WebFlux)
	`spring-boot-tomcat` (Tomcat)
	`spring-boot-jetty` (Jetty)
	`spring-boot-jackson` (Jackson)
`spring-boot-starter-web`	`spring-boot-starter-webmvc` (renamed)
`spring-boot-starter-webflux`	`spring-boot-starter-webflux` (unchanged)

The auto-configuration packages have moved too:

org.springframework.boot.autoconfigure.web.servlet → org.springframework.boot.webmvc.autoconfigure
org.springframework.boot.autoconfigure.web.reactive → org.springframework.boot.webflux.autoconfigure

7.10.2. Undertow Is Gone

Spring Boot 4 requires a Servlet 6.1 baseline, and Undertow isn't compatible with it. Undertow has been removed entirely:

"Spring Boot 4.0 requires a Servlet 6.1 baseline, with which Undertow is not yet compatible. As a result, Undertow support is dropped, including the Undertow starter and the ability to use Undertow as an embedded server."

What remains: Tomcat, Jetty, and Netty (for WebFlux).

7.10.3. Class Relocations

The embedded server classes have moved:

Boot 3	Boot 4
`org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory`	`org.springframework.boot.tomcat.TomcatServletWebServerFactory`
`org.springframework.boot.web.embedded.netty.NettyReactiveWebServerFactory`	`org.springframework.boot.netty.NettyReactiveWebServerFactory`

7.10.4. What Hasn't Changed

The ServletWebServerFactory mechanism — the same abstraction.
ServletContextInitializer — the same SPI.
ErrorMvcAutoConfiguration / BasicErrorController — the same logic.
WebMvcAutoConfiguration — the same beans, just in different packages.
WebServerFactoryCustomizer — the same interface.

7.11. Diagram: Creating the Web Server (Servlet)

refresh()
  └─ AbstractApplicationContext.refresh()
        ├─ ...
        └─ onRefresh()                          ← overridden in ServletWebServerApplicationContext
              │
              └─ createWebServer()
                    ├─ getWebServerFactory()
                    │     └─ TomcatServletWebServerFactory (from ServletWebServerFactoryAutoConfiguration)
                    │
                    ├─ factory.getWebServer(getSelfInitializer())
                    │     └─ TomcatServletWebServerFactory.getWebServer()
                    │           ├─ new Tomcat()
                    │           ├─ context = tomcat.addContext()
                    │           ├─ initializer.onStartup(servletContext)   ← the callback
                    │           │     └─ ServletContextInitializerBeans
                    │           │           ├─ DispatcherServletRegistrationBean
                    │           │           ├─ FilterRegistrationBean
                    │           │           └─ ServletListenerRegistrationBean
                    │           └─ return new TomcatWebServer(tomcat)
                    │
                    ├─ registerSingleton("webServerStartStop", 
                    │     new WebServerStartStopLifecycle(...))
                    │
                    └─ registerSingleton("webServerGracefulShutdown", 
                          new WebServerGracefulShutdownLifecycle(...))
        │
        └─ finishRefresh()
              └─ lifecycleProcessor.onRefresh()
                    └─ WebServerStartStopLifecycle.start()    ← phase = MAX-1
                          ├─ tomcat.start()
                          ├─ publishEvent(ServletWebServerInitializedEvent)
                          └─ running = true

7.12. Key Takeaways

ServletWebServerFactoryAutoConfiguration picks Tomcat/Jetty/Undertow from the classpath. @AutoConfigureOrder(HIGHEST_PRECEDENCE).
onRefresh() → createWebServer() is where the server is born. It runs inside refresh(), before finishRefresh().
ServletContextInitializer is the SPI for registering servlets, filters, and listeners. DispatcherServletRegistrationBean is one of its implementations.
WebServerStartStopLifecycle is a SmartLifecycle with phase = MAX-1 — it starts Tomcat after all the other beans.
DispatcherServletAutoConfiguration creates the DispatcherServlet and its registration. Ordered after ServletWebServerFactoryAutoConfiguration.
WebMvcAutoConfiguration wires up MVC: HandlerMapping, HandlerAdapter, HttpMessageConverters. Opt out via @EnableWebMvc.
ErrorMvcAutoConfiguration — /error + BasicErrorController. This isn't MVC; it's a Boot add-on.
ServletWebServerFactoryCustomizer applies the server.* properties. @Order(0) — user-defined customizers run after it.
The reactive stack: NettyReactiveWebServerFactory + DispatcherHandler. A different model, different APIs. 10 Boot 4: modularization (47 modules), spring-boot-starter-webmvc, Undertow removed, packages relocated. The mechanism itself — unchanged.

Spring Boot Under the Hood. Part 6: Bean Lifecycle — Born, Post-Processed, Destroyed

Silver_dev — Wed, 23 Sep 2026 22:15:48 +0000

By this point we have:

A fully built ApplicationContext (Part 3)
BeanDefinitions registered by scanning (Part 4)
Auto-configurations loaded (Part 5)

Now refresh() has to turn all those BeanDefinitions into living objects — beans. Let's go through it step by step.

6.1. BeanDefinition — the Bean's Blueprint

Before we talk about the lifecycle, we need to understand what a BeanDefinition is.

public interface BeanDefinition extends AttributeAccessor, BeanMetadataElement {
    String getBeanClassName();
    String getScope();
    boolean isLazyInit();
    boolean isPrimary();
    String[] getDependsOn();
    boolean isAutowireCandidate();
    ConstructorArgumentValues getConstructorArgumentValues();
    MutablePropertyValues getPropertyValues();
    String getInitMethodName();
    String getDestroyMethodName();
    int getRole();
    // ...
}

A BeanDefinition is metadata about a bean, not the bean itself. From it, Spring learns:

Which class to instantiate
Which scope (singleton / prototype / request / session)
What to inject (constructor args / property values)
Which init/destroy method to call
Whether it's lazy or not

The implementation hierarchy:

Class	When it's used
`RootBeanDefinition`	The main implementation (the merge result)
`ChildBeanDefinition`	Legacy, for parent-child definitions
`GenericBeanDefinition`	The modern one (used in configurations)
`AnnotatedGenericBeanDefinition`	For annotated classes (`@Configuration`, `@Component`)
`ScannedGenericBeanDefinition`	For classes found by scanning
`ConfigurationClassBeanDefinition`	For `@Bean` methods

A key feature: a BeanDefinition can act as a parent for other BeanDefinitions. When creating a bean, Spring performs a merge — combining parent and child into a RootBeanDefinition. This is called a MergedBeanDefinition.

6.2. The Full Bean Lifecycle — an Overview

Here is the complete scheme. We'll break down every step:

1.  BeanDefinition registered (scanning / @Bean / .imports)
2.  BeanFactoryPostProcessor.postProcessBeanFactory()
3.  BeanPostProcessor registration
4.  getBean() is called
5.  ─── for singletons ───
6.  MergedBeanDefinition is created (parent/child merge)
7.  InstantiationAwareBeanPostProcessor.postProcessBeforeInstantiation()
8.  InstantiationAwareBeanPostProcessor.determineCandidateConstructors()
9.  Constructor invoked (or factory method)
10. MergedBeanDefinitionPostProcessor.postProcessMergedBeanDefinition()
11. InstantiationAwareBeanPostProcessor.postProcessAfterInstantiation()
12. InstantiationAwareBeanPostProcessor.postProcessProperties()
       └─ @Autowired / @Value / @Resource
13. Aware interfaces: BeanNameAware, BeanClassLoaderAware, BeanFactoryAware
       └─ ApplicationContextAware, EnvironmentAware, ...
14. BeanPostProcessor.postProcessBeforeInitialization()
       └─ @PostConstruct (CommonAnnotationBeanPostProcessor)
15. InitializingBean.afterPropertiesSet()
16. @Bean(initMethod="...")
17. BeanPostProcessor.postProcessAfterInitialization()
       └─ AOP proxy goes here (AbstractAutoProxyCreator)
18. ─── singleton cache ───
19. Bean ready to use
20. ─── at shutdown ───
21. DestructionAwareBeanPostProcessor.postProcessBeforeDestruction()
       └─ @PreDestroy
22. DisposableBean.destroy()
23. @Bean(destroyMethod="...")

6.3. BeanFactoryPostProcessor — Working with Metadata

This is the first stage. A BeanFactoryPostProcessor (BFPP) works with BeanDefinitions — before any beans are created.

@FunctionalInterface
public interface BeanFactoryPostProcessor {
    void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory);
}

It's invoked by AbstractApplicationContext.invokeBeanFactoryPostProcessors(). The order:

BeanDefinitionRegistryPostProcessor.postProcessBeanDefinitionRegistry() — registers new BeanDefinitions
BeanFactoryPostProcessor.postProcessBeanFactory() — modifies existing ones

The main BFPP in Spring is ConfigurationClassPostProcessor. It:

Processes @Configuration, @Bean, @ComponentScan, @Import, @EnableAutoConfiguration
Registers BeanDefinitions for all the beans it finds

This is where Parts 3–4 take place. ConfigurationClassPostProcessor has the highest precedence (Ordered.HIGHEST_PRECEDENCE), so it runs first.

Your own BFPP:

public class MyBeanFactoryPostProcessor implements BeanFactoryPostProcessor {
    @Override
    public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) {
        BeanDefinition bd = beanFactory.getBeanDefinition("myService");
        bd.setScope(BeanDefinition.SCOPE_PROTOTYPE);
    }
}

Registration: @Component or a @Bean method. Don't inject other beans into it — at this stage they don't exist yet.

6.4. BeanPostProcessor — Working with Beans

A BeanPostProcessor (BPP) is invoked for every bean as it's being created.

public interface BeanPostProcessor {
    default Object postProcessBeforeInitialization(Object bean, String beanName) {
        return bean;
    }
    default Object postProcessAfterInitialization(Object bean, String beanName) {
        return bean;
    }
}

Two methods — before and after initialization. This is where all of Spring's magic is built: @Autowired, @PostConstruct, AOP proxies, @Transactional.

The BPP hierarchy

BeanPostProcessor
  ├─ InstantiationAwareBeanPostProcessor
  │     ├─ postProcessBeforeInstantiation()  ← before the bean is created
  │     ├─ postProcessAfterInstantiation()   ← after creation, before injection
  │     └─ postProcessProperties()           ← dependency injection
  │
  ├─ SmartInstantiationAwareBeanPostProcessor
  │     └─ determineCandidateConstructors()  ← constructor selection
  │
  ├─ MergedBeanDefinitionPostProcessor
  │     └─ postProcessMergedBeanDefinition() ← collecting metadata for injection
  │
  └─ DestructionAwareBeanPostProcessor
        └─ postProcessBeforeDestruction()    ← @PreDestroy

Built-in Spring BPPs

BPP	What it does	Order
`AutowiredAnnotationBeanPostProcessor`	`@Autowired`, `@Value`, `@Inject`	`Ordered.LOWEST_PRECEDENCE - 2`
`CommonAnnotationBeanPostProcessor`	`@PostConstruct`, `@PreDestroy`, `@Resource`	`Ordered.LOWEST_PRECEDENCE - 3`
`ConfigurationPropertiesBindingPostProcessor`	`@ConfigurationProperties`	`Ordered.HIGHEST_PRECEDENCE + 1`
`ApplicationListenerDetector`	Registers `ApplicationListener` beans	`LOWEST_PRECEDENCE`
`AbstractAutoProxyCreator`	AOP proxies (`@Transactional`, `@Async`, `@Cacheable`)	depends on the implementation

Important: BPP ordering is critical. For example, @PostConstruct must run before AOP proxying — otherwise the @PostConstruct method would be invoked on the proxy, not on the target object.

6.5. Bean Creation — a Step-by-Step Breakdown

Let's walk through doCreateBean() from AbstractAutowireCapableBeanFactory — the central bean-creation method.

Step 1: `createBean()` — the entry point

@Override
protected Object createBean(String beanName, RootBeanDefinition mbd, Object[] args) {
    // 1. Give BPPs a chance to return a proxy instead of the real bean
    Object bean = resolveBeforeInstantiation(beanName, mbdToUse);
    if (bean != null) {
        return bean;
    }

    // 2. Actual creation
    return doCreateBean(beanName, mbdToUse, args);
}

Step 2: `resolveBeforeInstantiation()` — the early proxy

protected Object resolveBeforeInstantiation(String beanName, RootBeanDefinition mbd) {
    Object bean = null;
    if (!Boolean.FALSE.equals(mbd.beforeInstantiationResolved)) {
        if (!mbd.isSynthetic() && hasInstantiationAwareBeanPostProcessors()) {
            Class<?> targetType = determineTargetType(beanName, mbd);
            bean = applyBeanPostProcessorsBeforeInstantiation(targetType, beanName);
            if (bean != null) {
                bean = applyBeanPostProcessorsAfterInitialization(bean, beanName);
            }
        }
    }
    return bean;
}

InstantiationAwareBeanPostProcessor.postProcessBeforeInstantiation() can return a ready-made object — in which case the regular creation cycle is skipped entirely. This is used, for example, for @Configuration proxies and in some AOP scenarios.

Step 3: doCreateBean() — the core logic

protected Object doCreateBean(String beanName, RootBeanDefinition mbd, Object[] args) {
    // 1. Instantiate (constructor / factory method)
    BeanWrapper instanceWrapper = null;
    if (mbd.isSingleton()) {
        instanceWrapper = this.factoryBeanInstanceCache.remove(beanName);
    }
    if (instanceWrapper == null) {
        instanceWrapper = createBeanInstance(beanName, mbd, args);
    }
    Object bean = instanceWrapper.getWrappedInstance();

    // 2. MergedBeanDefinitionPostProcessor
    applyMergedBeanDefinitionPostProcessors(mbd, beanType, beanName);

    // 3. Early registration (for circular dependencies)
    boolean earlySingletonExposure = (mbd.isSingleton() && this.allowCircularReferences 
        && isSingletonCurrentlyInCreation(beanName));
    if (earlySingletonExposure) {
        addSingletonFactory(beanName, () -> getEarlyBeanReference(beanName, mbd, bean));
    }

    // 4. Populate — inject dependencies
    Object exposedObject = bean;
    populateBean(beanName, mbd, instanceWrapper);

    // 5. Initialize
    exposedObject = initializeBean(beanName, exposedObject, mbd);

    // 6. Circular dependency check
    if (earlySingletonExposure) {
        Object earlySingletonReference = getSingleton(beanName, false);
        // ...
    }

    return exposedObject;
}

Step 4: `createBeanInstance()` — choosing the constructor

protected BeanWrapper createBeanInstance(String beanName, RootBeanDefinition mbd, Object[] args) {
    // 1. If there's a factory method — use it
    if (mbd.getFactoryMethodName() != null) {
        return instantiateUsingFactoryMethod(beanName, mbd, args);
    }

    // 2. Determine the constructor
    Constructor<?>[] ctors = determineConstructorsFromBeanPostProcessors(beanClass, beanName);
    if (ctors != null || mbd.getResolvedAutowireMode() == AUTOWIRE_CONSTRUCTOR 
            || mbd.hasConstructorArgumentValues() || !ObjectUtils.isEmpty(args)) {
        return autowireConstructor(beanName, mbd, ctors, args);
    }

    // 3. The default constructor
    return instantiateBean(beanName, mbd);
}

determineConstructorsFromBeanPostProcessors() calls SmartInstantiationAwareBeanPostProcessor.determineCandidateConstructors(). This is where AutowiredAnnotationBeanPostProcessor finds the @Autowired constructor (or the single constructor).

Step 5: `populateBean()` — injecting dependencies

protected void populateBean(String beanName, RootBeanDefinition mbd, BeanWrapper bw) {
    // 1. postProcessAfterInstantiation — a BPP can veto injection
    if (!mbd.isSynthetic() && hasInstantiationAwareBeanPostProcessors()) {
        for (InstantiationAwareBeanPostProcessor bp : getBeanPostProcessorCache().instantiationAware) {
            if (!bp.postProcessAfterInstantiation(bw.getWrappedInstance(), beanName)) {
                return;
            }
        }
    }

    // 2. postProcessProperties — the injection itself
    PropertyValues pvs = (mbd.hasPropertyValues() ? mbd.getPropertyValues() : null);
    if (pvs != null || hasInstantiationAwareBeanPostProcessors()) {
        for (InstantiationAwareBeanPostProcessor bp : getBeanPostProcessorCache().instantiationAware) {
            PropertyValues pvsToUse = bp.postProcessProperties(pvs, bw.getWrappedInstance(), beanName);
            // ...
        }
    }

    // 3. applyPropertyValues — setting values (for XML configs)
    if (pvs != null) {
        applyPropertyValues(beanName, mbd, bw, pvs);
    }
}

This is where AutowiredAnnotationBeanPostProcessor.postProcessProperties() finds @Autowired fields and setters and injects them.

Step 6: `initializeBean()` — initialization

protected Object initializeBean(String beanName, Object bean, RootBeanDefinition mbd) {
    // 1. Aware interfaces
    invokeAwareMethods(beanName, bean);   // BeanNameAware, BeanClassLoaderAware, BeanFactoryAware

    // 2. postProcessBeforeInitialization
    Object wrappedBean = bean;
    if (mbd == null || !mbd.isSynthetic()) {
        wrappedBean = applyBeanPostProcessorsBeforeInitialization(wrappedBean, beanName);
    }

    // 3. init-method
    try {
        invokeInitMethods(beanName, wrappedBean, mbd);
    } catch (Throwable ex) {
        throw new BeanCreationException(...);
    }

    // 4. postProcessAfterInitialization
    if (mbd == null || !mbd.isSynthetic()) {
        wrappedBean = applyBeanPostProcessorsAfterInitialization(wrappedBean, beanName);
    }

    return wrappedBean;
}

invokeAwareMethods()

private void invokeAwareMethods(String beanName, Object bean) {
    if (bean instanceof Aware) {
        if (bean instanceof BeanNameAware bna) {
            bna.setBeanName(beanName);
        }
        if (bean instanceof BeanClassLoaderAware bcla) {
            ClassLoader bcl = getBeanClassLoader();
            if (bcl != null) bcla.setBeanClassLoader(bcl);
        }
        if (bean instanceof BeanFactoryAware bfa) {
            bfa.setBeanFactory(this);
        }
    }
}

These are only three of the Aware interfaces. The rest (ApplicationContextAware, EnvironmentAware, ResourceLoaderAware, ApplicationEventPublisherAware, MessageSourceAware) are handled by ApplicationContextAwareProcessor — a BeanPostProcessor registered by the context.

applyBeanPostProcessorsBeforeInitialization()

This is where CommonAnnotationBeanPostProcessor.postProcessBeforeInitialization() runs — the one that invokes @PostConstruct methods.

The ordering of multiple BPPs follows @Order / Ordered. CommonAnnotationBeanPostProcessor has Ordered.LOWEST_PRECEDENCE - 3, so @PostConstruct runs later than other beforeInitialization callbacks but earlier than AOP proxying (which happens in afterInitialization).

invokeInitMethods()

protected void invokeInitMethods(String beanName, Object bean, RootBeanDefinition mbd) {
    boolean isInitializingBean = (bean instanceof InitializingBean);
    if (isInitializingBean && (mbd == null || !mbd.hasAnyExternallyManagedInitMethod("afterPropertiesSet"))) {
        ((InitializingBean) bean).afterPropertiesSet();
    }
    if (mbd != null && bean.getClass() != NullBean.class) {
        String initMethodName = mbd.getInitMethodName();
        if (StringUtils.hasLength(initMethodName) 
                && !(isInitializingBean && "afterPropertiesSet".equals(initMethodName))
                && !mbd.hasAnyExternallyManagedInitMethod(initMethodName)) {
            invokeCustomInitMethod(beanName, bean, mbd);
        }
    }
}

The order: InitializingBean.afterPropertiesSet() → @Bean(initMethod=...). @PostConstruct was already invoked earlier, in postProcessBeforeInitialization.

The final initialization order:

@PostConstruct
InitializingBean.afterPropertiesSet()
@Bean(initMethod = "...")

applyBeanPostProcessorsAfterInitialization()

This is where the AOP proxy is created. AbstractAutoProxyCreator.postProcessAfterInitialization() checks whether the bean carries @Transactional, @Async, @Cacheable, etc., and if so, wraps it in a proxy (CGLIB or a JDK dynamic proxy).

Key point: after afterInitialization, it's the proxy — not the original object — that goes into the singleton cache. All subsequent @Autowired injections will receive the proxy.

6.6. Call Order — a Summary Table

For a MyService bean with the full set of callbacks:

#	Callback	Invoked by
1	Constructor	`createBeanInstance()`
2	`@Autowired` fields/setters	`AutowiredAnnotationBeanPostProcessor`
3	`BeanNameAware.setBeanName()`	`invokeAwareMethods()`
4	`BeanFactoryAware.setBeanFactory()`	`invokeAwareMethods()`
5	`ApplicationContextAware.setApplicationContext()`	`ApplicationContextAwareProcessor`
6	`@PostConstruct`	`CommonAnnotationBeanPostProcessor`
7	`InitializingBean.afterPropertiesSet()`	`invokeInitMethods()`
8	`@Bean(initMethod)`	`invokeInitMethods()`
9	AOP proxy	`AbstractAutoProxyCreator`
10	Bean ready	Singleton cache
11	`@PreDestroy`	`CommonAnnotationBeanPostProcessor`
12	`DisposableBean.destroy()`	`DisposableBeanAdapter`
13	`@Bean(destroyMethod)`	`DisposableBeanAdapter`

6.7. Circular Dependencies

The problem:

A → B → A

If A needs B and B needs A — the classic deadlock.

Spring's solution: the three-level cache.

public class DefaultSingletonBeanRegistry {
    // Level 1: fully initialized singleton beans
    private final Map<String, Object> singletonObjects = new ConcurrentHashMap<>(256);

    // Level 2: early singletons (before populate/init)
    private final Map<String, Object> earlySingletonObjects = new ConcurrentHashMap<>(16);

    // Level 3: singleton factories (lambdas producing early references)
    private final Map<String, ObjectFactory<?>> singletonFactories = new HashMap<>(16);
}

The getSingleton() algorithm:

Check singletonObjects → if present, return it.
Check earlySingletonObjects → if present, return it.
Check singletonFactories → if present, invoke the factory, put the result into earlySingletonObjects, return it.
Otherwise — create the bean.

An example:

We start creating A → put an ObjectFactory into level 3.
Injecting B into A → we start creating B.
B needs A → getSingleton("A") → level 3 → early reference → returns the half-finished A.
B finishes initializing completely.
We resume initializing A → A is ready.

Limitations:

Works for singletons only.
Doesn't work with constructor injection — neither bean can be fully created through a constructor, because the constructor runs before the bean is registered in the cache. The fix: @Lazy on one of the parameters.
Spring Boot 2.6+ bans circular references by default. Re-enable via spring.main.allow-circular-references=true.

6.8. @lazy — Deferred Initialization

@Service
public class A {
    @Autowired
    @Lazy
    private B b;
}

Spring injects a proxy for B; the real bean is created on first access. This sidesteps circular dependencies.

@Lazy on a @Configuration class makes the entire configuration lazy. @Lazy on a @Bean method makes that bean lazy.

6.9. ObjectProvider and @Lookup

ObjectProvider

@Service
public class MyService {
    @Autowired
    private ObjectProvider<PrototypeBean> prototypeBeanProvider;

    public void doWork() {
        PrototypeBean bean = prototypeBeanProvider.getObject();  // a new one every time
    }
}

An ObjectProvider is a lazy resolver. getObject() asks the container for the bean every time. It works for the prototype scope too.

@Lookup

@Service
public abstract class MyService {
    @Lookup
    protected abstract PrototypeBean createPrototypeBean();
}

Spring generates a subclass (CGLIB) that overrides the method and asks the container for the bean. An older approach — ObjectProvider is preferred.

6.10. Bean Destruction

registerShutdownHook()

Called from SpringApplication.refreshContext():

private void refreshContext(ConfigurableApplicationContext context) {
    if (this.registerShutdownHook) {
        try {
            context.registerShutdownHook();
        } catch (AccessControlException ex) { }
    }
    refresh(context);
}

registerShutdownHook() adds a JVM shutdown hook that will call context.close() when the JVM terminates.

close() → doClose()

protected void doClose() {
    // 1. LifecycleProcessor.onClose() — stops Lifecycle beans
    if (this.lifecycleProcessor != null) {
        this.lifecycleProcessor.onClose();
    }

    // 2. Destroy the beans
    destroyBeans();

    // 3. Close the BeanFactory
    closeBeanFactory();

    // 4. onClose()
    onClose();

    // 5. Reset the listeners
    if (this.earlyApplicationListeners != null) {
        this.applicationListeners.clear();
        this.applicationListeners.addAll(this.earlyApplicationListeners);
    }

    // 6. active = false
    this.active.set(false);
}

destroyBeans() → destroySingleton()

public void destroySingleton(String beanName) {
    removeSingleton(beanName);
    DisposableBean disposableBean = this.disposableBeans.remove(beanName);
    if (disposableBean != null) {
        disposableBean.destroy();
    }
}

DisposableBeanAdapter.destroy() calls, in order:

DestructionAwareBeanPostProcessor.postProcessBeforeDestruction() → @PreDestroy
DisposableBean.destroy()
@Bean(destroyMethod) or AutoCloseable.close()

Important: Spring automatically calls close() on beans implementing AutoCloseable / Closeable unless you say otherwise. Disable it via @Bean(destroyMethod = "").

6.11. SmartLifecycle and Lifecycle

Lifecycle is an interface for beans with start/stop phases:

public interface Lifecycle {
    void start();
    void stop();
    boolean isRunning();
}

SmartLifecycle extends it:

public interface SmartLifecycle extends Lifecycle, Phased {
    boolean isAutoStartup();
    void stop(Runnable callback);
    int getPhase();
}

The LifecycleProcessor (by default, DefaultLifecycleProcessor) drives:

onRefresh() — calls start() on all beans with isAutoStartup(), ordered by getPhase() (ascending)
onClose() — calls stop() on all of them, in descending getPhase() order

Example: WebServerStartStopLifecycle — starts/stops Tomcat.

6.12. Spring Boot 3 vs Spring Boot 4

Aspect	Spring Boot 3	Spring Boot 4
Bean lifecycle	Unchanged	Unchanged
BeanPostProcessor	The same interfaces	The same interfaces
Circular references	Banned by default (since 2.6)	Banned
AOT	Present, but opt-in	More aggressive, reflection-free by default
`@ConstructorBinding`	Optional	Legacy
`BeanRegistrar`	Introduced in Spring Framework 7	The primary registration approach for AOT

With AOT (Boot 3.x / 4.x), Spring generates code that registers BeanDefinitions programmatically, without reflection. @PostConstruct, @Autowired, and other callbacks turn into direct code calls. It's faster and compatible with GraalVM native images.

6.13. Diagram: the Complete Bean Lifecycle

BeanDefinition
    │
    ▼
BeanFactoryPostProcessor.postProcessBeanFactory()   ← works with metadata
    │
    ▼
BeanPostProcessors registered in the context
    │
    ▼
getBean(beanName)
    │
    ├─ in singletonObjects?  → yes → return (already built)
    │
    ▼
createBean()
    │
    ├─ resolveBeforeInstantiation()
    │     └─ InstantiationAwareBeanPostProcessor.postProcessBeforeInstantiation()
    │           └─ if it returned an object → return (shortcut)
    │
    ▼
doCreateBean()
    │
    ├─ 1. createBeanInstance()
    │       ├─ determineCandidateConstructors()    ← the @Autowired constructor
    │       └─ new Instance() / factory method
    │
    ├─ 2. applyMergedBeanDefinitionPostProcessors()
    │       └─ @Autowired metadata is collected
    │
    ├─ 3. addSingletonFactory()                    ← early cache (for circulars)
    │
    ├─ 4. populateBean()
    │       ├─ postProcessAfterInstantiation()
    │       └─ postProcessProperties()             ← @Autowired / @Value
    │
    ├─ 5. initializeBean()
    │       ├─ invokeAwareMethods()                ← BeanNameAware, BeanFactoryAware
    │       ├─ postProcessBeforeInitialization()
    │       │     ├─ ApplicationContextAwareProcessor
    │       │     └─ CommonAnnotationBeanPostProcessor → @PostConstruct
    │       ├─ invokeInitMethods()
    │       │     ├─ InitializingBean.afterPropertiesSet()
    │       │     └─ @Bean(initMethod)
    │       └─ postProcessAfterInitialization()
    │             └─ AbstractAutoProxyCreator → AOP proxy
    │
    ├─ 6. addSingleton()                           ← the finished bean goes into the cache
    │
    ▼
Bean ready
    │
    ▼ (at shutdown)
destroySingleton()
    ├─ DestructionAwareBeanPostProcessor.postProcessBeforeDestruction()
    │     └─ @PreDestroy
    ├─ DisposableBean.destroy()
    └─ @Bean(destroyMethod) / AutoCloseable.close()

6.14. Key Takeaways

A BeanDefinition is metadata, not a bean. From it, Spring learns everything about the future object.
A BeanFactoryPostProcessor works with metadata before beans are created. The main BFPP is ConfigurationClassPostProcessor.
A BeanPostProcessor works with beans. Every bean passes through the BPP chain.
The initialization order: @PostConstruct → InitializingBean.afterPropertiesSet() → @Bean(initMethod).
The AOP proxy is created in postProcessAfterInitialization(). After that, the singleton cache holds the proxy, not the original.
Circular dependencies are resolved via the three-level cache — but only for singletons and never for constructor injection.
@Lazy and ObjectProvider are the ways around circular dependencies.
Destruction: @PreDestroy → DisposableBean.destroy() → @Bean(destroyMethod) → AutoCloseable.close().
SmartLifecycle is for beans with start/stop phases (e.g., the web server).
Boot 4 + AOT: the lifecycle turns into generated code, reflection is minimized.

Spring Boot Under the Hood. Part 5: The Heart of Spring Boot — How Auto-configuration Works

Silver_dev — Wed, 23 Sep 2026 18:40:26 +0000

Auto-configuration is the heart of Spring Boot. It's what lets you add spring-boot-starter-web to your pom.xml and instantly get Tomcat, DispatcherServlet, Jackson, and a bunch of other beans — without a single line of configuration.

Let's break down how it works, down to the last detail.

5.1. Where the Entry Point Lives

You already know that @SpringBootApplication includes @EnableAutoConfiguration. Let's look at it:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@AutoConfigurationPackage
@Import(AutoConfigurationImportSelector.class)
public @interface EnableAutoConfiguration {
    Class<?>[] exclude() default {};
    String[] excludeName() default {};
}

Two key points:

@AutoConfigurationPackage — remembers the main class's package (we covered this in Part 4).
@Import(AutoConfigurationImportSelector.class) — imports the selector that does all the magic.

@Import is a Spring Framework mechanism that lets you add BeanDefinitions to the context programmatically, bypassing scanning. A selector implements ImportSelector and returns an array of class names to register.

5.2. AutoConfigurationImportSelector — the Master Conductor

public class AutoConfigurationImportSelector 
        implements DeferredImportSelector, BeanClassLoaderAware, 
                   ResourceLoaderAware, BeanFactoryAware, EnvironmentAware, Ordered {

Note: this is a DeferredImportSelector, not a plain ImportSelector. The difference is fundamental.

5.2.1. DeferredImportSelector vs ImportSelector

Type	When it's processed
`ImportSelector`	Immediately, while parsing `@Configuration`
`DeferredImportSelector`	After all regular `@Configuration` classes have been processed

This guarantees that auto-configurations are processed after user-defined beans. That's exactly why @ConditionalOnMissingBean in auto-configurations works correctly — by the time they're processed, all of your @Bean methods are already registered.

5.2.2. selectImports() — the entry point

@Override
public String[] selectImports(AnnotationMetadata importingClassMetadata) {
    AutoConfigurationEntry autoConfigurationEntry = 
        getAutoConfigurationEntry(annotationMetadata);
    return StringUtils.toStringArray(autoConfigurationEntry.getConfigurations());
}

The getAutoConfigurationEntry() method is the central one. Let's break it down.

5.3. getAutoConfigurationEntry() — a Step-by-Step Breakdown

protected AutoConfigurationEntry getAutoConfigurationEntry(
        AnnotationMetadata annotationMetadata) {

    // 1. Check: is auto-configuration enabled at all?
    if (!isEnabled(annotationMetadata)) {
        return EMPTY_ENTRY;
    }

    // 2. Get the @EnableAutoConfiguration attributes (exclude, excludeName)
    AnnotationAttributes attributes = getAttributes(annotationMetadata);

    // 3. Load ALL candidates from the classpath
    List<String> configurations = getCandidateConfigurations(
        annotationMetadata, attributes);

    // 4. Deduplicate
    configurations = removeDuplicates(configurations);

    // 5. Apply exclusions
    Set<String> exclusions = getExclusions(annotationMetadata, attributes);
    checkExcludedClasses(configurations, exclusions);
    configurations.removeAll(exclusions);

    // 6. Filter by conditions (ConfigurationClassFilter)
    configurations = getConfigurationClassFilter().filter(configurations);

    // 7. Publish the AutoConfigurationImportEvent
    fireAutoConfigurationImportEvents(configurations, exclusions);

    return new AutoConfigurationEntry(configurations, exclusions);
}

The key steps are 3 and 6.

5.4. Loading the Candidates — .imports Instead of spring.factories

5.4.1. A Bit of History

Version	Mechanism
Spring Boot 1.x – 2.6	`META-INF/spring.factories` (the EnableAutoConfiguration key)
Spring Boot 2.7	Both mechanisms in parallel (backward compatibility)
Spring Boot 3.0+	`.imports` only; `spring.factories` registration for auto-configurations removed

This is confirmed by the official documentation and release notes: "Spring Boot 2.7 introduced a new META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports file for registering auto-configurations, while maintaining backwards compatibility with registration in spring.factories. With this release, support for registering auto-configurations in spring.factories has been removed in favor of the imports file."

5.4.2. What the .imports File Looks Like

The file path:

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

The format — one line = one class:

org.springframework.boot.autoconfigure.admin.SpringApplicationAdminJmxAutoConfiguration
org.springframework.boot.autoconfigure.aop.AopAutoConfiguration
org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration
org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration
...

For comparison, the old spring.factories used a key-value format:

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
org.springframework.boot.autoconfigure.aop.AopAutoConfiguration,\
org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration

The advantages of .imports: simpler parsing, no escaping issues, better AOT compatibility.

5.4.3. ImportCandidates — the loader

Candidates are loaded via ImportCandidates.load():

public static ImportCandidates load(Class<?> annotation, ClassLoader classLoader) {
    String location = String.format(
        "META-INF/spring/%s.imports", annotation.getName());
    List<String> candidates = new ArrayList<>();
    // ... reads all files at this location from all JARs
    return new ImportCandidates(candidates);
}

Key point: ImportCandidates does not use SpringFactoriesLoader (which reads spring.factories). It's a separate mechanism optimized for AOT and native images.

5.4.4. @AutoConfiguration — the new annotation

Since Spring Boot 2.7, auto-configuration classes are marked with @AutoConfiguration instead of @Configuration:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Configuration(proxyBeanMethods = false)
@AutoConfigureBefore
@AutoConfigureAfter
public @interface AutoConfiguration {
    @AliasFor(annotation = AutoConfigureBefore.class, attribute = "value")
    Class<?>[] before() default {};

    @AliasFor(annotation = AutoConfigureAfter.class, attribute = "value")
    Class<?>[] after() default {};
}

Three key differences from @Configuration:

proxyBeanMethods = false — auto-configurations are not proxied with CGLIB. It's faster and avoids circular dependencies.
It carries @AutoConfigureBefore / @AutoConfigureAfter — the ordering can be specified right in the annotation.
It's semantically separated from user-defined @Configuration classes.

5.5. Conditional Annotations (@Conditional*) — Filtering the Candidates

After all the candidates are loaded (there are 150+ of them in Spring Boot 3.x), filtering begins. This is where the conditional annotations come into play.

5.5.1. How It's Wired

The filtering happens in ConfigurationClassFilter:

class ConfigurationClassFilter {
    private final List<AutoConfigurationImportFilter> filters;

    List<String> filter(List<String> configurations) {
        String[] candidates = configurations.toArray(new String[0]);
        boolean[] skip = new boolean[candidates.length];
        boolean skipped = false;
        for (AutoConfigurationImportFilter filter : this.filters) {
            boolean[] match = filter.match(candidates, this.autoConfigurationMetadata);
            for (int i = 0; i < match.length; i++) {
                if (!match[i]) {
                    skip[i] = true;
                    skipped = true;
                }
            }
        }
        // ... returns the filtered list
    }
}

AutoConfigurationImportFilter is an SPI interface whose implementations are loaded via spring.factories (yes, spring.factories is still used for internal SPIs — just not for auto-configuration registration). Spring Boot ships three filters:

Filter	What it checks
`OnClassCondition`	`@ConditionalOnClass` / `@ConditionalOnMissingClass`
`OnBeanCondition`	`@ConditionalOnBean` / `@ConditionalOnMissingBean`
`OnWebApplicationCondition`	`@ConditionalOnWebApplication` / `@ConditionalOnNotWebApplication`

Important: this is the first stage of filtering — a coarse-grained pass. It only checks for the presence of classes and beans, without loading the auto-configurations themselves. Finer-grained checks (properties, resources, expressions) happen later, when ConfigurationClassParser processes each specific class.

5.5.2. The Main Conditional Annotations

@ConditionalOnClass / @ConditionalOnMissingClass

@AutoConfiguration
@ConditionalOnClass(DataSource.class)   // activates only if DataSource is on the classpath
public class DataSourceAutoConfiguration { }

The check happens via ASM — the class is not loaded into the JVM; only the .class file's metadata is read. That's why it's safe to reference classes that may not be present at runtime.

@ConditionalOnBean / @ConditionalOnMissingBean

@Bean
@ConditionalOnMissingBean
public DataSource dataSource() {
    return new HikariDataSource();
}

The key customization mechanism. If you've declared your own DataSource, the auto-configuration backs off and doesn't create its own. This is exactly why auto-configurations are processed as a DeferredImportSelector — so that all of your beans are already registered by the time the checks run.

Caveat: @ConditionalOnMissingBean only works reliably for @Bean methods and @Configuration classes that are processed after yours. If you put it on a regular @Configuration, the result can be unpredictable — @conditionals are evaluated while parsing the @Configuration, and the parsing order may differ from the bean registration order.

@ConditionalOnProperty

@AutoConfiguration
@ConditionalOnProperty(
    prefix = "spring.datasource", 
    name = "url", 
    matchIfMissing = false
)
public class DataSourceAutoConfiguration { }

Checks the value of a property. matchIfMissing = true means "activate if the property is missing entirely."

@ConditionalOnResource

@ConditionalOnResource(resources = "classpath:my-config.properties")

@ConditionalOnWebApplication / @ConditionalOnNotWebApplication

@ConditionalOnWebApplication(type = Type.SERVLET)

@ConditionalOnExpression

@ConditionalOnExpression("${my.feature.enabled:false} and '${my.mode}' == 'advanced'")

Uses SpEL. Not recommended for auto-configurations — it's slow and plays poorly with AOT.

5.5.3. ConfigurationPhase — a Subtlety

A @Conditional can be evaluated on two phases:

public enum ConfigurationPhase {
    PARSE_CONFIGURATION,  // while parsing @Configuration
    REGISTER_BEAN         // while registering beans
}

@ConditionalOnBean and @ConditionalOnMissingBean use REGISTER_BEAN, because they need to know which beans are already registered. The rest (@ConditionalOnClass, @ConditionalOnProperty) use PARSE_CONFIGURATION.

5.6. Auto-configuration Ordering

When you have 150+ auto-configurations, the order in which they're applied is critical. For example, DataSourceAutoConfiguration must come before JpaRepositoriesAutoConfiguration.

5.6.1. @AutoConfigureBefore / @AutoConfigureAfter

@AutoConfiguration(after = DataSourceAutoConfiguration.class)
public class JpaRepositoriesAutoConfiguration { }

Or via the standalone annotations:

@AutoConfiguration
@AutoConfigureAfter(DataSourceAutoConfiguration.class)
public class JpaRepositoriesAutoConfiguration { }

These annotations don't guarantee an absolute order — they only define a relative one. Spring Boot sorts the dependency graph via AutoConfigurationSorter.

5.6.2. @AutoConfigureOrder

@AutoConfiguration
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)
public class MyEarlyAutoConfiguration { }

The semantics are the same as @Order, but for auto-configurations. It's used when auto-configurations know nothing about each other and can't reference one another via before/after.

5.6.3. AutoConfigurationSorter — how the sorting works

class AutoConfigurationSorter {
    void sort(List<String> classNames) {
        // 1. Reads each class's metadata (ASM)
        // 2. Builds the graph: A before B, A after C
        // 3. Topological sort
        // 4. Resolves conflicts via @AutoConfigureOrder
    }
}

Priority: @AutoConfigureBefore / @AutoConfigureAfter > @AutoConfigureOrder.

5.7. Creating Your Own Auto-configuration

5.7.1. The auto-configuration class

@AutoConfiguration
@ConditionalOnClass(MyService.class)
@EnableConfigurationProperties(MyServiceProperties.class)
public class MyServiceAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MyService myService(MyServiceProperties properties) {
        return new MyService(properties.getEndpoint(), properties.getTimeout());
    }
}

5.7.2. Properties

@ConfigurationProperties(prefix = "my.service")
public class MyServiceProperties {
    private String endpoint = "http://localhost:8080";
    private Duration timeout = Duration.ofSeconds(5);
    // getters/setters
}

5.7.3. Registration in .imports

The file:

src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

The content:

com.example.autoconfigure.MyServiceAutoConfiguration

5.7.4. The starter

So that users can add a single dependency, you ship a starter — an empty JAR that pulls in:

<dependency>
    <groupId>com.example</groupId>
    <artifactId>my-service-spring-boot-starter</artifactId>
</dependency>

Inside the starter's pom.xml:

<dependencies>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>my-service</artifactId>
    </dependency>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>my-service-spring-boot-autoconfigure</artifactId>
    </dependency>
</dependencies>

Naming convention: xxx-spring-boot-starter (for users) and xxx-spring-boot-autoconfigure (for the auto-configuration code).

5.8. Spring Boot 3 vs Spring Boot 4: Key Differences

5.8.1. Modularization of spring-boot-autoconfigure

This is the biggest change in Boot 4.

Aspect	Spring Boot 3.x	Spring Boot 4.x
Artifact	A single monolithic `spring-boot-autoconfigure` (2 MiB in 3.5)	47 modular JARs, one per technology
Size	Everything in one place	Only the modules you need end up on the classpath
Web auto-configurations	In `spring-boot-autoconfigure`	In `spring-boot-webmvc` / `spring-boot-webflux`
JPA auto-configurations	In `spring-boot-autoconfigure`	In `spring-boot-data-jpa`
IDE hints	All classes of all technologies	Only the ones actually in use

The official announcement explains the motivation: "Instead of a single, monolithic spring-boot-autoconfigure jar, we are now splitting functionality into small and more focused modules. This change is motivated by maintainability, clarity, and a leaner runtime footprint."

5.8.2. What Hasn't Changed

@EnableAutoConfiguration — works the same way.
AutoConfigurationImportSelector — the same mechanism.
.imports files — the same format.
@Conditional* — the same annotations.
@AutoConfigureBefore / @AutoConfigureAfter — the same semantics.

5.8.3. BeanRegistrar — the new alternative

In Spring Framework 7 / Boot 4, BeanRegistrar arrived — programmatic bean registration without @Bean methods:

public class MyBeanRegistrar implements BeanRegistrar {
    @Override
    public void register(BeanRegistry registry, Environment env) {
        if (env.acceptsProfiles(Profiles.of("dev"))) {
            registry.registerBean("myService", MyService.class, 
                spec -> spec.supplier(ctx -> new MyService("dev")));
        }
    }
}

It's registered via @Import(MyBeanRegistrar.class). This is closer to the AOT approach: beans are registered programmatically rather than via reflection.

5.8.4. Starters

Boot 3	Boot 4
`spring-boot-starter-web`	`spring-boot-starter-webmvc`
`spring-boot-starter-webflux`	`spring-boot-starter-webflux` (unchanged)
`spring-boot-starter-data-jpa`	`spring-boot-starter-data-jpa` (unchanged)

5.9. Diagram: the Full Path of Auto-configuration

@SpringBootApplication
  └─ @EnableAutoConfiguration
        └─ @Import(AutoConfigurationImportSelector.class)
              │
              └─ refresh() → invokeBeanFactoryPostProcessors()
                    └─ ConfigurationClassPostProcessor
                          └─ ConfigurationClassParser
                                └─ DeferredImportSelectorGroupingHandler
                                      └─ AutoConfigurationImportSelector.selectImports()
                                            │
                                            ├─ 1. isEnabled()?
                                            ├─ 2. getAttributes() → exclude/excludeName
                                            ├─ 3. getCandidateConfigurations()
                                            │     └─ ImportCandidates.load()
                                            │           └─ META-INF/spring/...AutoConfiguration.imports
                                            │                 (all JARs)
                                            ├─ 4. removeDuplicates()
                                            ├─ 5. getExclusions() → removeAll()
                                            ├─ 6. ConfigurationClassFilter.filter()
                                            │     ├─ OnClassCondition
                                            │     ├─ OnBeanCondition
                                            │     └─ OnWebApplicationCondition
                                            └─ 7. fireAutoConfigurationImportEvents()
                                                  │
                                                  ▼
                                            A list of class names
                                                  │
                                                  ▼
                                            ConfigurationClassParser processes
                                            each class as a @Configuration
                                                  │
                                                  ▼
                                            @Bean methods → BeanDefinitions
                                            @Conditional* → final filtering

5.10. Key Takeaways

@EnableAutoConfiguration → AutoConfigurationImportSelector is the single entry point. The selector is a DeferredImportSelector, so auto-configurations are processed after user-defined beans.
.imports files (Boot 3+) replaced spring.factories for auto-configurations. The path: META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports.
@AutoConfiguration is the new annotation for auto-configuration classes: proxyBeanMethods = false, carries @AutoConfigureBefore/After.
@Conditional* annotations work in two passes: coarse-grained filtering via AutoConfigurationImportFilter (by classes/beans), then fine-grained via ConfigurationClassParser.
@ConditionalOnMissingBean is the "back-off" mechanism: if you've declared your own bean, the auto-configuration backs off.
Ordering is defined by @AutoConfigureBefore / @AutoConfigureAfter (relative) and @AutoConfigureOrder (absolute). Sorting is done by AutoConfigurationSorter.
Boot 4 — modularization: 47 modules instead of a single spring-boot-autoconfigure. The auto-configuration mechanism itself hasn't changed, only the packaging.
Your own auto-configuration = @AutoConfiguration + @ConditionalOnClass + @ConditionalOnMissingBean + an .imports file + a starter.

Spring Boot Under the Hood. Part 4: @SpringBootApplication — Three Annotations, Three Mechanisms

Silver_dev — Wed, 23 Sep 2026 16:26:03 +0000

We've reached the point where the BeanDefinitionLoader (Part 3) has registered the BeanDefinition for your main class. But that's where the magic of @SpringBootApplication only begins — the class itself is marked with this annotation, and it kicks off three independent mechanisms. Let's break down each one.

4.1. @SpringBootApplication — a Composed Annotation

Let's look at its definition (Spring Boot 3.x):

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@SpringBootConfiguration
@EnableAutoConfiguration
@ComponentScan(excludeFilters = { 
    @Filter(type = FilterType.CUSTOM, classes = TypeExcludeFilter.class),
    @Filter(type = FilterType.CUSTOM, classes = AutoConfigurationExcludeFilter.class) 
})
public @interface SpringBootApplication {
    // aliases for @ComponentScan
    @AliasFor(annotation = ComponentScan.class, attribute = "basePackages")
    String[] scanBasePackages() default {};

    @AliasFor(annotation = ComponentScan.class, attribute = "basePackageClasses")
    Class<?>[] scanBasePackageClasses() default {};

    // aliases for @EnableAutoConfiguration
    @AliasFor(annotation = EnableAutoConfiguration.class)
    Class<?>[] exclude() default {};

    @AliasFor(annotation = EnableAutoConfiguration.class)
    String[] excludeName() default {};
}

Key point: @SpringBootApplication is not "one annotation that does everything" — it's three separate annotations, each kicking off its own mechanism. And each of them is processed at a different time, by different classes.

4.2. The Three Mechanisms and When They Fire

Annotation	What it does	When it fires	Processed by
`@SpringBootConfiguration`	Marks the class as `@Configuration`	`ConfigurationClassPostProcessor`	`ConfigurationClassParser`
`@ComponentScan`	Looks for `@Component`s in the package	`ConfigurationClassPostProcessor`	`ComponentScanAnnotationParser`
`@EnableAutoConfiguration`	Loads auto-configurations	`ConfigurationClassPostProcessor`	`AutoConfigurationImportSelector`

All three are processed inside ConfigurationClassPostProcessor — a BeanFactoryPostProcessor invoked by refreshContext() during invokeBeanFactoryPostProcessors(). That is, before regular beans are created.

The diagram:

refreshContext()
  └─ AbstractApplicationContext.refresh()
        └─ invokeBeanFactoryPostProcessors()
              └─ ConfigurationClassPostProcessor.postProcessBeanDefinitionRegistry()
                    └─ ConfigurationClassParser.parse()
                          ├─ @SpringBootConfiguration → registerAsConfigClass()
                          ├─ @ComponentScan         → doProcessConfigurationClass() → scan()
                          └─ @EnableAutoConfiguration → AutoConfigurationImportSelector

4.3. @SpringBootConfiguration — "I'm a Configuration"

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Configuration
@Indexed
public @interface SpringBootConfiguration {
    @AliasFor(annotation = Configuration.class)
    boolean proxyBeanMethods() default true;
}

It's just @Configuration with a label saying "I'm Spring Boot's main configuration class." Why a separate annotation? To:

Distinguish the main class from other @Configuration classes (used in tests: @SpringBootTest looks specifically for @SpringBootConfiguration).
Add @Indexed (more on that below).

proxyBeanMethods = true (the default) means the class will be wrapped in a CGLIB proxy, and calls to @Bean methods within the class will be intercepted — this guarantees that a bean is created only once (singleton semantics).

4.4. @ComponentScan — How Scanning Works

4.4.1. Where the Base Package Comes From

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Repeatable(ComponentScans.class)
public @interface ComponentScan {
    @AliasFor("basePackages")
    String[] value() default {};

    @AliasFor("value")
    String[] basePackages() default {};

    Class<?>[] basePackageClasses() default {};

    // ...
}

If neither basePackages nor basePackageClasses is specified, scanning starts from the package of the class the annotation is on.

package com.example.myapp;   // ← the root package

@SpringBootApplication
public class MyApplication { }

Everything under com.example.myapp and its sub-packages (com.example.myapp.service, com.example.myapp.web, etc.) will be found.

4.4.2. Why the "Root Package" Matters

If you put your main class in com.example.myapp and a service in com.other.service, the service won't be found. This isn't a Spring bug — it's standard scanning behavior.

Correct:

com.example.myapp
  ├─ MyApplication.java      ← @SpringBootApplication
  ├─ service/
  │    └─ UserService.java   ← @Service  ✅ will be found
  └─ web/
       └─ UserController.java ← @Controller ✅ will be found

Incorrect:

com.example.myapp
  └─ MyApplication.java

com.other.service            ← outside the root package
  └─ UserService.java        ← @Service  ❌ NOT found

The exception is if you specify scanBasePackages explicitly:

@SpringBootApplication(scanBasePackages = {"com.example.myapp", "com.other.service"})

4.4.3. basePackageClasses — a Type-Safe Alternative

Instead of strings, you can pass marker classes:

@SpringBootApplication(
    scanBasePackageClasses = {MyApplication.class, AnotherMarker.class}
)

The packages are derived automatically from the packages of the given classes. This is safer: if you refactor (rename a package), the compiler will catch the mistake.

4.4.4. What Exactly the Scanner Looks For

ClassPathBeanDefinitionScanner looks for classes marked with stereotype annotations:

Annotation	Semantics
`@Component`	the base stereotype
`@Service`	business logic
`@Repository`	data access (+ exception translation)
`@Controller`	MVC controller
`@RestController`	`@Controller` + `@ResponseBody`
`@Configuration`	configuration class (also a component)

Important: all of them are meta-annotated with @Component. The scanner looks for @Component following the chain of meta-annotations.

4.4.5. The Mechanics of Scanning — ClassPathScanningCandidateComponentProvider

This class does the heavy lifting:

public class ClassPathScanningCandidateComponentProvider {
    private final List<TypeFilter> includeFilters = new ArrayList<>();
    private final List<TypeFilter> excludeFilters = new ArrayList<>();

    public Set<BeanDefinition> findCandidateComponents(String basePackage) {
        // 1. Collect all .class files in the package
        // 2. For each, read the metadata (via ASM, not reflection!)
        // 3. Apply the include/exclude filters
        // 4. Return the matching BeanDefinitions
    }
}

Key point: the metadata is read via ASM (SimpleMetadataReader), not via Class.forName(). This means the scanner doesn't load classes during scanning — it only reads the headers of .class files. Reflection comes into play later, at bean creation time.

4.5. Filters: includeFilters and excludeFilters

4.5.1. FilterType — Five Strategies

public enum FilterType {
    ANNOTATION,        // by annotation
    ASSIGNABLE_TYPE,   // by type (class/interface)
    ASPECTJ,           // by AspectJ expression
    REGEX,             // by regex on the class name
    CUSTOM             // your own TypeFilter
}

Examples:

// ANNOTATION: include everything annotated with @MyService
@ComponentScan(includeFilters = @Filter(type = FilterType.ANNOTATION, 
    classes = MyService.class))

// ASSIGNABLE_TYPE: include everything that implements Animal
@ComponentScan(includeFilters = @Filter(type = FilterType.ASSIGNABLE_TYPE, 
    classes = Animal.class))

// CUSTOM: your own logic
@ComponentScan(includeFilters = @Filter(type = FilterType.CUSTOM, 
    classes = MyCustomFilter.class))

When multiple classes are listed in a single @Filter, OR logic applies: "the type is annotated with @foo OR @bar".

4.5.2. useDefaultFilters — an Important Flag

@ComponentScan(
    useDefaultFilters = false,
    includeFilters = @Filter(type = FilterType.ANNOTATION, 
        classes = MyService.class)
)

By default, useDefaultFilters = true, meaning the scanner automatically includes @Component, @Service, @Repository, and @Controller. If you want to match only your own annotations, set it to false.

4.5.3. TypeExcludeFilter — Spring Boot's Extensible Filter

Recall that @SpringBootApplication contains:

@ComponentScan(excludeFilters = { 
    @Filter(type = CUSTOM, classes = TypeExcludeFilter.class),
    @Filter(type = CUSTOM, classes = AutoConfigurationExcludeFilter.class) 
})

TypeExcludeFilter is an extension point. It doesn't filter anything on its own. Instead, at startup it fetches all beans implementing TypeExcludeFilter from the BeanFactory and applies their match() methods:

public class TypeExcludeFilter implements TypeFilter, BeanFactoryAware {
    @Override
    public boolean match(MetadataReader metadataReader, 
            MetadataReaderFactory metadataReaderFactory) {
        if (this.beanFactory instanceof ListableBeanFactory lbf) {
            Collection<TypeExcludeFilter> filters = lbf.getBeansOfType(
                TypeExcludeFilter.class).values();
            return filters.stream().anyMatch(filter -> 
                filter.match(metadataReader, metadataReaderFactory));
        }
        return false;
    }
}

This lets you plug in your own filters via @Bean:

@Bean
MyExcludeFilter myExcludeFilter() {
    return new MyExcludeFilter();
}

Your filter will be applied automatically during scanning. It's a powerful but little-known mechanism.

4.5.4. AutoConfigurationExcludeFilter — the Second Built-in Filter

This filter excludes auto-configurations from scanning. The logic:

@Override
public boolean match(MetadataReader metadataReader, 
        MetadataReaderFactory factory) {
    return isConfiguration(metadataReader) && isAutoConfiguration(metadataReader);
}

In other words, if a class is a @Configuration and is an auto-configuration (registered in .imports / spring.factories), it is not picked up by component scanning. Auto-configurations are loaded separately, via @EnableAutoConfiguration. Without this filter, they would be registered twice.

4.6. @AutoConfigurationPackage — the "Hidden" Annotation

Let's look at the definition of @EnableAutoConfiguration once more:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@AutoConfigurationPackage
@Import(AutoConfigurationImportSelector.class)
public @interface EnableAutoConfiguration {
    // ...
}

@AutoConfigurationPackage is what remembers the package of your main class:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@Import(AutoConfigurationPackages.Registrar.class)
public @interface AutoConfigurationPackage { }

AutoConfigurationPackages.Registrar registers an AutoConfigurationPackages.BasePackages bean holding the list of base packages. Why? So that other auto-configurations know where to look for your entities:

Spring Data JPA (@EntityScan) — uses the base package to find @Entity classes.
Spring Data MongoDB — the same.
Spring Boot DevTools — for restarts.

If you put an @Entity outside the root package, JPA won't find it — because @AutoConfigurationPackage only remembered com.example.myapp.

4.7. @Indexed and META-INF/spring.components — Speeding Up Scanning

4.7.1. The Problem

At startup, Spring Boot scans the classpath. In large projects this can take seconds — especially when there are many JARs on the classpath.

4.7.2. The Solution: @Indexed

Spring Framework 5.0 introduced @Indexed:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Indexed { }

All stereotype annotations (@Component, @Service, @Repository, @Controller, @Configuration, @SpringBootConfiguration) are meta-annotated with @Indexed.

4.7.3. How It Works

At compile time, an annotation processor (spring-context-indexer) generates the file:

META-INF/spring.components

Example content:

com.example.myapp.service.UserService=org.springframework.stereotype.Component
com.example.myapp.web.UserController=org.springframework.stereotype.Component
com.example.myapp.config.AppConfig=org.springframework.context.annotation.Configuration

At startup, CandidateComponentsIndexLoader reads this file and builds a CandidateComponentsIndex. Instead of scanning the classpath, ClassPathScanningCandidateComponentProvider simply reads the index.

4.7.4. How to Enable It

Option 1 — the annotation on the main class:

@SpringBootApplication
@Indexed
public class MyApplication { }

Option 2 — a dependency + annotation processor:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context-indexer</artifactId>
    <optional>true</optional>
</dependency>

Important caveat: @Indexed switches on the index. If an index exists, scanning goes through it. If an index exists but you've added a new @Component without recompiling, it won't be found. The index must be rebuilt on every build.

4.8. Diagram: the Full Path of @ComponentScan

ConfigurationClassPostProcessor.postProcessBeanDefinitionRegistry()
  │
  └─ ConfigurationClassParser.parse()
        │
        ├─ processConfigurationClass(MyApplication.class)
        │     │
        │     ├─ @SpringBootConfiguration → registerAsConfigClass()
        │     │
        │     ├─ @ComponentScan → doProcessConfigurationClass()
        │     │     │
        │     │     ├─ ComponentScanAnnotationParser.parse()
        │     │     │     ├─ basePackages = {pkg(MyApplication)}
        │     │     │     ├─ excludeFilters = [TypeExcludeFilter, AutoConfigurationExcludeFilter]
        │     │     │     └─ useDefaultFilters = true
        │     │     │
        │     │     └─ ClassPathBeanDefinitionScanner.doScan(basePackages)
        │     │           │
        │     │           ├─ CandidateComponentsIndexLoader.loadIndex()   ← @Indexed
        │     │           │     └─ if the index exists → read spring.components
        │     │           │
        │     │           └─ findCandidateComponents(basePackage)
        │     │                 ├─ for each .class:
        │     │                 │     ├─ SimpleMetadataReader (ASM)
        │     │                 │     ├─ isCandidateComponent() → include/exclude
        │     │                 │     └─ if it passes → BeanDefinition
        │     │                 │
        │     │                 └─ registerBeanDefinition()
        │     │
        │     └─ @EnableAutoConfiguration → AutoConfigurationImportSelector
        │           └─ auto-configuration loading   ← Part 5
        │
        └─ ...

4.9. Spring Boot 3 vs Spring Boot 4

Aspect	Spring Boot 3.x	Spring Boot 4.x
`@ComponentScan`	Unchanged	Unchanged
`@SpringBootApplication`	Unchanged	Unchanged
New mechanism	—	`BeanRegistrar` — programmatic bean registration as an alternative to scanning
Modularity	`spring-boot-autoconfigure` — a monolith	47 modular JARs, each with its own scanning
Starters	`spring-boot-starter-web`	`spring-boot-starter-webmvc`
`@Indexed`	Works	Works, but less relevant due to AOT

The main thing in Boot 4: the core behavior of @ComponentScan and @SpringBootApplication hasn't changed. But there's a new player — BeanRegistrar, an alternative way to register beans without scanning:

public class MyBeanRegistrar implements BeanRegistrar {
    @Override
    public void register(BeanRegistry registry, Environment env) {
        if (env.acceptsProfiles(Profiles.of("dev"))) {
            registry.registerBean("myService", MyService.class);
        }
    }
}

This is closer to the AOT approach: beans are registered programmatically rather than discovered by scanning.

4.10. Key Takeaways

@SpringBootApplication = three annotations, all processed by ConfigurationClassPostProcessor during refresh().
The base package for scanning = the main class's package. Anything outside it won't be found unless you specify scanBasePackages explicitly.
ClassPathBeanDefinitionScanner reads metadata via ASM without loading the classes.
TypeExcludeFilter is an extensible point: you can add your own filter via a @Bean method.
AutoConfigurationExcludeFilter keeps auto-configurations out of component scanning so they aren't registered twice.
@AutoConfigurationPackage remembers the base package for JPA/Spring Data and other auto-configurations.
@Indexed + META-INF/spring.components speeds up scanning in large projects.
Boot 4: the core behavior is unchanged, but BeanRegistrar has appeared as an alternative to scanning.

Spring Boot Under the Hood. Part 3: Assembling the Container — How Boot Builds Its ApplicationContext

Silver_dev — Tue, 22 Sep 2026 21:23:26 +0000

3.1. What Is an ApplicationContext and Why There Are Several

ApplicationContext is an extended BeanFactory that adds:

ApplicationEvent support (publish/subscribe)
MessageSource (i18n)
ResourceLoader (file access)
Automatic registration of BeanPostProcessors / BeanFactoryPostProcessors
Context hierarchy (parent/child)

In Spring Boot there are three basic context types — one per WebApplicationType:

WebApplicationType	Context class	Module (Boot 4)
SERVLET	AnnotationConfigServletWebServerApplicationContext	spring-boot-webmvc
REACTIVE	AnnotationConfigReactiveWebServerApplicationContext	spring-boot-webflux
NONE	AnnotationConfigApplicationContext	spring-boot (core)

The key difference between AnnotationConfigServletWebServerApplicationContext and a plain AnnotationConfigApplicationContext is that the former knows how to create and manage an embedded web server (Tomcat/Jetty). It extends ServletWebServerApplicationContext, which implements WebServerApplicationContext and contains methods like createWebServer() and getWebServer().

3.2. createApplicationContext() — Choosing the Context

This step in SpringApplication.run() looks like this:

protected ConfigurableApplicationContext createApplicationContext() {
    return this.applicationContextFactory.create(this.webApplicationType);
}

ApplicationContextFactory is a functional interface (since Spring Boot 2.4) responsible for creating the context based on the application type:

@FunctionalInterface
public interface ApplicationContextFactory {
    ConfigurableApplicationContext create(WebApplicationType webApplicationType);

    // ... factory methods of(...)
}

The default implementation (ApplicationContextFactory.DEFAULT) looks roughly like this:

ApplicationContextFactory DEFAULT = (webApplicationType) -> {
    try {
        switch (webApplicationType) {
            case SERVLET:
                return new AnnotationConfigServletWebServerApplicationContext();
            case REACTIVE:
                return new AnnotationConfigReactiveWebServerApplicationContext();
            default:
                return new AnnotationConfigApplicationContext();
        }
    } catch (Exception ex) {
        throw new IllegalStateException(
            "Unable create a default ApplicationContext instance, "
            + "you may need a custom ApplicationContextFactory", ex);
    }
};

How to customize it

// Approach 1: via SpringApplication
SpringApplication app = new SpringApplication(MyApp.class);
app.setApplicationContextFactory(ctx -> new MyCustomContext());

// Approach 2: via SpringApplicationBuilder
new SpringApplicationBuilder(MyApp.class)
    .contextFactory(ApplicationContextFactory.of(MyCustomContext::new))
    .run(args);

ApplicationContextFactory.of(Supplier<ConfigurableApplicationContext>) creates a factory that simply calls the supplied Supplier.

Gotcha. The context you return must be "raw" — Spring Boot itself will call setEnvironment(), prepareContext(), and refresh(). If you return an already refreshed context, you'll end up with double initialization.

3.3. `prepareContext()` — Preparing the Context Before refresh

This is the busiest step. Here is its full skeleton (Spring Boot 3.x):

private void prepareContext(DefaultBootstrapContext bootstrapContext,
        ConfigurableApplicationContext context,
        ConfigurableEnvironment environment,
        SpringApplicationRunListeners listeners,
        ApplicationArguments applicationArguments,
        Banner printedBanner) {

    // 1. Set the Environment
    context.setEnvironment(environment);

    // 2. Post-process the context (bean name generator, resource loader, ConversionService)
    postProcessApplicationContext(context);

    // 3. Apply the ApplicationContextInitializers
    applyInitializers(context);

    // 4. Publish ApplicationContextInitializedEvent
    listeners.contextPrepared(context);

    // 5. Log startup info and profiles
    if (this.logStartupInfo) {
        logStartupInfo(context.getParent() == null);
        logStartupProfileInfo(context);
    }

    // 6. Register Boot-specific singleton beans
    ConfigurableListableBeanFactory beanFactory = context.getBeanFactory();
    beanFactory.registerSingleton("springApplicationArguments", applicationArguments);
    if (printedBanner != null) {
        beanFactory.registerSingleton("springBootBanner", printedBanner);
    }

    // 7. Configure allowBeanDefinitionOverriding
    if (beanFactory instanceof DefaultListableBeanFactory dlbf) {
        dlbf.setAllowBeanDefinitionOverriding(this.allowBeanDefinitionOverriding);
    }

    // 8. Lazy initialization
    if (this.lazyInitialization) {
        context.addBeanFactoryPostProcessor(
            new LazyInitializationBeanFactoryPostProcessor());
    }

    // 9. Load all sources (the main @Configuration class, etc.)
    Set<Object> sources = getAllSources();
    load(context, sources.toArray(new Object[0]));

    // 10. Publish ApplicationPreparedEvent
    listeners.contextLoaded(context);
}

We briefly touched on this step in Part 1 — now let's break down the key steps in depth.

Step 1: `context.setEnvironment(environment)`

The Environment prepared in Part 2 is handed over to the context. From this moment on, EnvironmentAware beans and @Value annotations can read properties.

Step 2: `postProcessApplicationContext()`

protected void postProcessApplicationContext(ConfigurableApplicationContext context) {
    if (this.beanNameGenerator != null) {
        context.getBeanFactory().registerSingleton(
            AnnotationConfigUtils.CONFIGURATION_BEAN_NAME_GENERATOR,
            this.beanNameGenerator);
    }
    if (this.resourceLoader != null) {
        if (context instanceof GenericApplicationContext gac) {
            gac.setResourceLoader(this.resourceLoader);
        }
        context.getBeanFactory().registerResolvableDependency(
            ResourceLoader.class, this.resourceLoader);
    }
    if (this.addConversionService) {
        context.getBeanFactory().setConversionService(
            ApplicationConversionService.getSharedInstance());
    }
}

Three things:

BeanNameGenerator — the bean naming strategy (default: AnnotationBeanNameGenerator).
ResourceLoader — where to read resources from (default: DefaultResourceLoader).
ConversionService — ApplicationConversionService for type conversion (used by @ConfigurationProperties and @Value).

Step 3: `applyInitializers()` — Extension Point #1

protected void applyInitializers(ConfigurableApplicationContext context) {
    for (ApplicationContextInitializer initializer : getInitializers()) {
        Class<?> requiredType = GenericTypeResolver.resolveTypeArgument(
            initializer.getClass(), ApplicationContextInitializer.class);
        Assert.isInstanceOf(requiredType, context,
            "Unable to call initializer.");
        initializer.initialize(context);
    }
}

ApplicationContextInitializer is an SPI interface from Spring Framework:

@FunctionalInterface
public interface ApplicationContextInitializer<C extends ConfigurableApplicationContext> {
    void initialize(C applicationContext);
}

It is invoked before refresh(), while the context is still empty. Typical scenarios:

Programmatically activating profiles: context.getEnvironment().addActiveProfile("dev")
Registering a PropertySource from a non-standard source
Setting a parent context

Registration via spring.factories:

# META-INF/spring.factories
org.springframework.context.ApplicationContextInitializer=\
com.example.MyInitializer

Programmatic registration:

SpringApplication app = new SpringApplication(MyApp.class);
app.addInitializers(ctx -> ctx.getEnvironment().addActiveProfile("metrics"));

Note: the built-in Spring Boot ApplicationContextInitializers (e.g., ConfigurationWarningsApplicationContextInitializer, ContextIdApplicationContextInitializer) are loaded in the SpringApplication constructor, not here. applyInitializers() invokes both them and the user-added ones.

Step 4: `listeners.contextPrepared()`

ApplicationContextInitializedEvent is published. At this point the context has been created, the Environment is set, and the initializers have been applied — but no beans have been loaded yet. This is the last chance to tamper with the context without risking breaking the dependency graph.

Step 5: logging the profiles

protected void logStartupProfileInfo(ConfigurableApplicationContext context) {
    Log log = getApplicationLog();
    if (log.isInfoEnabled()) {
        String[] activeProfiles = context.getEnvironment().getActiveProfiles();
        // ... prints: "The following 1 profile is active: \"dev\""
    }
}

This is the exact line you see in the logs at startup:

The following 1 profile is active: "dev"

Step 6: registering singleton beans

beanFactory.registerSingleton("springApplicationArguments", applicationArguments);
beanFactory.registerSingleton("springBootBanner", printedBanner);

These objects are not @Components — they are registered manually. Internally, registerSingleton() calls addSingleton() in DefaultSingletonBeanRegistry, i.e., it puts the object straight into the singleton cache, bypassing the regular bean lifecycle.

This means:

They cannot be proxied by a BeanPostProcessor
They don't go through @PostConstruct / InitializingBean
But they can be injected via @Autowired ApplicationArguments

Step 7: `allowBeanDefinitionOverriding`

if (beanFactory instanceof DefaultListableBeanFactory dlbf) {
    dlbf.setAllowBeanDefinitionOverriding(this.allowBeanDefinitionOverriding);
}

The default since Boot 2.1 is false. If two @Bean methods define a bean with the same name → BeanDefinitionOverrideException. You can allow it via spring.main.allow-bean-definition-overriding=true.

Step 8: getAllSources() + load() — entering the world of BeanDefinitions

protected Set<Object> getAllSources() {
    Set<Object> allSources = new LinkedHashSet<>();
    if (!CollectionUtils.isEmpty(this.primarySources)) {
        allSources.addAll(this.primarySources);
    }
    if (!CollectionUtils.isEmpty(this.sources)) {
        allSources.addAll(this.sources);
    }
    return Collections.unmodifiableSet(allSources);
}

primarySources is your @SpringBootApplication class. Additional sources can be added via SpringApplicationBuilder.sources(...).

Then — load():

protected void load(ApplicationContext context, Object[] sources) {
    BeanDefinitionLoader loader = createBeanDefinitionLoader(
        getBeanDefinitionRegistry(context), sources);
    // ...
    loader.load();
}

Step 9: `listeners.contextLoaded()`

ApplicationPreparedEvent is published. The context is ready for refresh().

3.4. BeanDefinitionLoader — the Facade for Bean Loading

This is the key class that turns your @Configuration classes into BeanDefinitions. It's not part of Spring Framework — it belongs to Spring Boot.

What it can do

BeanDefinitionLoader is a facade over three readers:

Source	Reader
`Class<?>` (your `@Configuration`)	`AnnotatedBeanDefinitionReader`
`Resource` (an XML file)	`XmlBeanDefinitionReader`
`Package` (a base package)	`ClassPathBeanDefinitionScanner`
`CharSequence` (a string)	Tries Class → Resource → Package

How it's structured

class BeanDefinitionLoader {
    private final BeanDefinitionRegistry registry;
    private final AnnotatedBeanDefinitionReader annotatedReader;
    private final XmlBeanDefinitionReader xmlReader;
    private final ClassPathBeanDefinitionScanner scanner;

    BeanDefinitionLoader(BeanDefinitionRegistry registry, Object... sources) {
        this.registry = registry;
        this.annotatedReader = new AnnotatedBeanDefinitionReader(registry);
        this.xmlReader = new XmlBeanDefinitionReader(registry);
        this.scanner = new ClassPathBeanDefinitionScanner(registry, false);
        // ... setEnvironment, setResourceLoader
    }
}

Note that the ClassPathBeanDefinitionScanner is created with the flag false — no default include filters. This means it does not scan for @Components automatically until you call scan(). The actual scanning happens later, when ConfigurationClassPostProcessor processes the @ComponentScan from your @SpringBootApplication.

How load() works

int load() {
    int count = 0;
    for (Object source : this.sources) {
        count += load(source);
    }
    return count;
}

private int load(Object source) {
    if (source instanceof Class<?> clazz)    return load(clazz);
    if (source instanceof Resource res)     return load(res);
    if (source instanceof Package pkg)      return load(pkg);
    if (source instanceof CharSequence cs)  return load(cs);
    throw new IllegalArgumentException("Invalid source type " + source.getClass());
}

For your @SpringBootApplication class, load(Class<?>) gets called:

private int load(Class<?> source) {
    if (isGroovyPresent() && GroovyBeanDefinitionSource.class.isAssignableFrom(source)) {
        // ... Groovy
    }
    if (isComponent(source)) {
        this.annotatedReader.register(source);
        return 1;
    }
    return 0;
}

In other words, if the class is marked @Component (and @SpringBootApplication includes @Component via meta-annotations), it is registered through AnnotatedBeanDefinitionReader. An AnnotatedGenericBeanDefinition is created, which stores the annotation metadata.

Important: at this point only the BeanDefinition for the @SpringBootApplication class itself is created. All the other beans (services, controllers, @Bean methods) will be registered later — during refresh(), when ConfigurationClassPostProcessor processes @ComponentScan, @Import, @Bean, and auto-configuration.

3.5. Diagram: from createApplicationContext() to ApplicationPreparedEvent

run()
 │
 ├─ createApplicationContext()
 │     └─ ApplicationContextFactory.create(webApplicationType)
 │           ├─ SERVLET   → AnnotationConfigServletWebServerApplicationContext
 │           ├─ REACTIVE  → AnnotationConfigReactiveWebServerApplicationContext
 │           └─ NONE      → AnnotationConfigApplicationContext
 │
 ├─ context.setApplicationStartup()
 │
 └─ prepareContext()
       │
       ├─ context.setEnvironment(environment)
       │
       ├─ postProcessApplicationContext()
       │     ├─ BeanNameGenerator
       │     ├─ ResourceLoader
       │     └─ ConversionService
       │
       ├─ applyInitializers()
       │     └─ ApplicationContextInitializer.initialize(context)
       │           (ConfigurationWarnings, ContextId, custom ones)
       │
       ├─ listeners.contextPrepared()
       │     └─ ApplicationContextInitializedEvent
       │
       ├─ logStartupProfileInfo()
       │
       ├─ beanFactory.registerSingleton("springApplicationArguments")
       ├─ beanFactory.registerSingleton("springBootBanner")
       │
       ├─ setAllowBeanDefinitionOverriding()
       │
       ├─ getAllSources() → {MyApplication.class}
       │
       ├─ load(context, sources)
       │     └─ BeanDefinitionLoader.load()
       │           └─ AnnotatedBeanDefinitionReader.register(MyApplication.class)
       │                 → BeanDefinition for @SpringBootApplication
       │
       └─ listeners.contextLoaded()
             └─ ApplicationPreparedEvent
                   │
                   ▼
             refreshContext()   ← Part 5

3.6. Spring Boot 3 vs Spring Boot 4: What Changed

ApplicationContextFactory — removed

In Spring Boot 3, ApplicationContextFactory is a public interface, part of the spring-boot core. In Spring Boot 4, it has been removed. Instead, a modular system is at work: each module (spring-boot-webmvc, spring-boot-webflux, spring-boot-core) registers its own context via META-INF/spring/...imports and spring.factories.

AbstractApplicationContextFactory is marked as @Deprecated(since="6.0", forRemoval=true) and is scheduled for removal. In other words, a transition period: it's still there in 3.x, gone in 4.x.

prepareContext() — almost unchanged

The logic of prepareContext() has stayed the same in Boot 4. The only thing that changed is where the context comes from — in Boot 3, ApplicationContextFactory was a field of SpringApplication, while in Boot 4 the context is created via the modular ApplicationContextFactory shipped with the corresponding starter.

BeanDefinitionLoader — unchanged

This class hasn't changed in either 3.x or 4.x. It's still package-private, still a facade over the three readers.

Starters

Boot 3	Boot 4
`spring-boot-starter-web`	`spring-boot-starter-webmvc`
`spring-boot-starter-webflux`	`spring-boot-starter-webflux` (unchanged)

3.7. Key Takeaways

ApplicationContextFactory is the context-selection strategy. In Boot 3 it's a public interface; in Boot 4 it's removed in favor of modularity.
prepareContext() is 10 steps, each of which can be extended: Initializer, BeanNameGenerator, ResourceLoader, ConversionService.
ApplicationContextInitializer is the only place where you can intervene in the context before any beans are loaded.
BeanDefinitionLoader doesn't create beans — it only registers the BeanDefinition for the primary source. The rest is the job of ConfigurationClassPostProcessor inside refresh().
springApplicationArguments and springBootBanner are registered as singletons directly, bypassing BeanPostProcessors.
ApplicationPreparedEvent is the last event before refresh(). After it, the context is "frozen" against external changes.
Boot 4: ApplicationContextFactory is gone, the context is determined by the modules. prepareContext() and BeanDefinitionLoader are unchanged.

Spring Boot Under the Hood. Part 2: Where Your application.yml Actually Goes

Silver_dev — Tue, 22 Sep 2026 18:03:36 +0000

2.1. What Is an Environment and Why You Need One

The Environment is a central Spring object responsible for two things:

Property sources — where the configuration is read from (files, env vars, args).
Profiles — which profiles are active.

The interface hierarchy:

Environment
  └─ ConfigurableEnvironment
        ├─ StandardEnvironment                   (NONE)
        ├─ StandardServletEnvironment            (SERVLET)
        └─ StandardReactiveWebEnvironment        (REACTIVE)

StandardServletEnvironment additionally mixes in ServletConfig and ServletContext as property sources.

2.2. Creating the Environment — getOrCreateEnvironment()

private ConfigurableEnvironment getOrCreateEnvironment() {
    if (this.environment != null) {
        return this.environment;
    }
    return this.applicationContextFactory.createEnvironment(
        this.webApplicationType);
}

In ApplicationContextFactory (Boot 3):

case SERVLET:
    return new StandardServletEnvironment();
case REACTIVE:
    return new StandardReactiveWebEnvironment();
default:
    return new StandardEnvironment();

Boot 4: the factory is gone — the Environment is created by the module (spring-boot-webmvc → StandardServletEnvironment).

2.3. MutablePropertySources — the Order of Precedence

Inside the Environment sits a MutablePropertySources — an ordered list of PropertySource objects. The one higher up wins.

The order for StandardServletEnvironment (top = highest priority):

#	PropertySource	Example
1	`commandLineArgs`	`--server.port=9090`
2	`servletConfigInitParams`	`<init-param>`
3	`servletContextInitParams`	`<context-param>`
4	`systemProperties`	`-Dserver.port=9090`
5	`systemEnvironment`	`SERVER_PORT=9090`
6	`random`	`random.int`, `random.uuid`
7	Config resource 'application.yml'	the configuration file
8	`defaultProperties`	`SpringApplication.setDefaultProperties()`

Key point: @PropertySource, application-{profile}.yml, and spring.config.import entries are inserted between the system sources and defaultProperties, each at its own index.

You can verify it like this:

@Autowired
private ConfigurableEnvironment env;

env.getPropertySources().forEach(ps ->
    System.out.println(ps.getName()));

2.4. configureEnvironment() — What Happens Before Files Are Read

protected void configureEnvironment(ConfigurableEnvironment environment,
        String[] args) {
    if (this.addCommandLineProperties) {
        addCommandLineProperties(environment, args);   // CommandLinePropertySource
    }
    configureProfiles(environment, args);              // active profiles
}

What happens here:

SimpleCommandLinePropertySource parses --key=value.
Profiles are read from spring.profiles.active (if passed via args or system properties) before any files are loaded.

2.5. EnvironmentPostProcessor — the Extension Point

A key SPI. Loaded from META-INF/spring.factories:

org.springframework.boot.env.EnvironmentPostProcessor=\
org.springframework.boot.context.config.ConfigDataEnvironmentPostProcessor,\
org.springframework.boot.env.RandomValuePropertySourceEnvironmentPostProcessor,\
...

The interface:

public interface EnvironmentPostProcessor {
    void postProcessEnvironment(ConfigurableEnvironment environment,
        SpringApplication application);
}

Ordered via @Order. Invoked by listeners.environmentPrepared(), i.e., before the ApplicationContext exists.

A custom example — adding your own property source from a database:

public class DbPropertySourcePostProcessor implements EnvironmentPostProcessor {
    @Override
    public void postProcessEnvironment(ConfigurableEnvironment env,
            SpringApplication app) {
        env.getPropertySources().addLast(
            new MapPropertySource("dbConfig", loadFromDb()));
    }
}

Registration:

# META-INF/spring.factories
org.springframework.boot.env.EnvironmentPostProcessor=\
com.example.DbPropertySourcePostProcessor

2.6. Loading Configuration Files (Boot 2.4+)

This is the meatiest part. Since 2.4 the whole mechanism has been completely rewritten — ConfigDataEnvironmentPostProcessor was introduced.

The chain:

ConfigDataEnvironmentPostProcessor.postProcessEnvironment()
  └─ ConfigDataEnvironment.processAndApply()
        ├─ ConfigDataLocationResolver   (for each location)
        │     └─ StandardConfigDataLocationResolver
        ├─ ConfigDataLoader             (for each resource)
        │     └─ StandardConfigDataLoader → PropertySource
        └─ Environment.getPropertySources().addXxx(...)

Key classes:

ConfigDataEnvironment — the orchestrator.
ConfigDataLocationResolver — turns the string file:./config/ into a ConfigDataResource.
ConfigDataLoader — loads a ConfigDataResource into ConfigData (a set of property sources).
ConfigData — an immutable container: a name + property sources.

What's searched by default

Default locations (in increasing order of precedence):

classpath:/
classpath:/config/
file:./
file:./config/
file:./config/*/

Files: application.properties / application.yml / application.yaml.

Plus profile-specific ones: application-{profile}.yml.

spring.config.*

Property	What it does
`spring.config.name`	the base name (default: `application`)
`spring.config.location`	replaces the default locations
`spring.config.additional-location`	adds to the defaults
`spring.config.import`	imports other sources
`spring.config.on-not-found`	`fail` / `ignore`

Example:

spring:
  config:
    import:
      - optional:file:./external.yml
      - configtree:/run/secrets/

Prefixes:

optional: — don't fail if it's missing.
file: / classpath: — explicit protocol.
configtree: — a directory of files, where each file is a property (the file name is the key).

YAML multi-document:

# application.yml
server:
  port: 8080
---
spring:
  config:
    activate:
      on-profile: prod
server:
  port: 9090

The second document is only activated in the prod profile.

Boot 4: the whole mechanism remains, but it's modular — spring-boot-config-data is a separate JAR.

2.7. Profiles

Activation
Methods (in decreasing order of precedence):

--spring.profiles.active=dev,metrics (args)
-Dspring.profiles.active=dev (system property)
SPRING_PROFILES_ACTIVE=dev (env var)
spring.profiles.active in application.yml
SpringApplication.setAdditionalProfiles("dev") (programmatically)

Profile groups (2.4+)

spring:
  profiles:
    group:
      "prod": "proddb,prodmq"
      "dev":  "devdb,devmq"

Activate prod → proddb and prodmq are enabled.

include / default

spring:
  profiles:
    include: common
    default: local

include — adds profiles to the active ones.
default — applies if nothing is activated.

Checking in code

@Profile("dev")
@Configuration
class DevConfig {}

@Autowired
private Environment env;

if (env.acceptsProfiles(Profiles.of("prod & !test"))) { ... }

Profiles.of() supports expression syntax: & (and), | (or), ! (not).

2.8. @ConfigurationProperties — Typed Access

Basic example

@ConfigurationProperties(prefix = "app.mail")
@Validated
public record MailProperties(
    @NotBlank String host,
    @Min(1) @Max(65535) int port,
    Duration timeout,
    List<String> recipients
) {}

Activation:

@SpringBootApplication
@ConfigurationPropertiesScan   // ← scans all @ConfigurationProperties classes
public class App {}

Or explicitly:

@EnableConfigurationProperties(MailProperties.class)

How binding works

The chain:

ConfigurationPropertiesBindingPostProcessor   (BeanPostProcessor)
  └─ ConfigurationPropertiesBinder
        ├─ Binder                    (Spring Framework)
        ├─ PropertySources           ← from the Environment
        ├─ ConversionService         ← type conversion
        └─ Validator                 ← JSR-380

ConfigurationPropertiesBindingPostProcessor is registered automatically via ConfigurationPropertiesAutoConfiguration.

Relaxed binding

Spring Boot matches keys in any style:

Format in the file	Matches the field
`app.mail.host-name`	`hostName`
`app.mail.host_name`	`hostName`
`app.mail.hostName`	`hostName`
`APP_MAIL_HOSTNAME`	`hostname`

The canonical format is kebab-case.

The evolution of @ConstructorBinding

Boot 2.x — required for immutable (constructor-bound) beans.
Boot 3.0+ — no longer needed for records and classes with a single constructor.
Boot 3.x — still used when a class has multiple constructors.
Boot 4 — effectively legacy, rarely used.

Validation

@ConfigurationProperties(prefix = "app.mail")
@Validated
public class MailProperties {
    @NotBlank private String host;
    @Min(1) private int port;
    // getters/setters
}

At startup, if validation fails → BindValidationException → ApplicationFailedEvent.

Binding complex types

Duration — 10s, 5m, 1h.
DataSize — 10MB, 512KB.
List<String> — app.mail.recipients=a,b,c or a YAML list.
Map<String, X> — nested keys.
Enum — by name (case-insensitive).

Boot 3 vs Boot 4

Aspect	Boot 3	Boot 4
`@ConstructorBinding`	Optional	Legacy
Module	`spring-boot`	`spring-boot-configuration-properties` (extracted)
Record binding	Supported	Supported
AOT processing	Present	Improved (reflection-free by default)

2.9. Diagram: a Property's Journey from File to Bean

application.yml
      │
      ▼
StandardConfigDataLoader
      │
      ▼
ConfigData (PropertySource "Config resource '...'")
      │
      ▼
MutablePropertySources.addLast()     ← inside the Environment
      │
      ▼
Binder.bind(prefix, targetClass)
      │  (via ConfigurationPropertiesBinder)
      ▼
MailProperties (bean)

2.10. Key Takeaways

The Environment is created before the ApplicationContext — which is why an EnvironmentPostProcessor can do pretty much anything.
ConfigDataEnvironmentPostProcessor is the entry point for loading application.yml (since Boot 2.4).
The order of property sources decides everything — higher in the list = wins.
spring.config.import is the only proper way to plug in external configuration in Boot 3/4.
@ConfigurationProperties + records is the modern standard; @ConstructorBinding is no longer needed.
Profile groups (spring.profiles.group.*) — handy for composition.
Boot 4: the configuration mechanism has been extracted into a separate module, spring-boot-config-data.

Spring Boot Under the Hood. Part 1: What Really Happens When You Call SpringApplication.run()

Silver_dev — Tue, 22 Sep 2026 10:43:45 +0000

1.1. The `main()` Entry Point — Anatomy of the Startup

Every Spring Boot application starts the same way:

@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

That single line sets the entire machinery in motion.

1.2. Static `run()` vs. a `SpringApplication` Instance

There are two ways to launch an application:

Approach 1 — the static method (95% of cases):

SpringApplication.run(MyApplication.class, args);

Under the hood, it does this:

public static ConfigurableApplicationContext run(Class<?> primarySource, String... args) {
    return new SpringApplication(primarySource).run(args);
}

So a SpringApplication instance is created first, and then its instance method run() is called. This is important to understand: all configuration happens in the constructor, while run() is pure execution.

Approach 2 — manual instantiation (when you need customization before the run):

public static void main(String[] args) {
    SpringApplication app = new SpringApplication(MyApplication.class);
    app.setBannerMode(Banner.Mode.OFF);
    app.setAdditionalProfiles("dev");
    app.setWebApplicationType(WebApplicationType.SERVLET);
    app.run(args);
}

This is exactly why a separate class exists — SpringApplicationBuilder — for fluent configuration:

new SpringApplicationBuilder(MyApplication.class)
    .profiles("dev")
    .bannerMode(Banner.Mode.OFF)
    .web(WebApplicationType.SERVLET)
    .run(args);

SpringApplicationBuilder is especially useful when you need to build a parent-child context hierarchy:

new SpringApplicationBuilder(ParentConfig.class)
    .child(ChildConfig.class)
    .run(args);

This approach is used in Spring Cloud (the bootstrap context) and in testing scenarios.

1.3. The SpringApplication Constructor — What Happens Before `run()`

The constructor does three key things:

1. Deducing the application type (WebApplicationType)

private WebApplicationType deduceWebApplicationType() {
    if (ClassUtils.isPresent(REACTIVE_WEB_ENVIRONMENT_CLASS, null)
            && !ClassUtils.isPresent(MVC_WEB_ENVIRONMENT_CLASS, null)) {
        return WebApplicationType.REACTIVE;
    }
    // ... checks for SERVLET and NONE
}

Spring Boot checks the classpath for specific marker classes (via ClassUtils.isPresent() — a class-presence check, not component scanning):

DispatcherServlet present (Spring MVC) → SERVLET
DispatcherHandler present (WebFlux) without MVC → REACTIVE
No web classes → NONE

2. Loading the ApplicationContextInitializers and ApplicationListeners

Via SpringFactoriesLoader, it reads META-INF/spring.factories:

org.springframework.context.ApplicationContextInitializer=\
org.springframework.boot.context.ConfigurationWarningsApplicationContextInitializer,\
org.springframework.boot.context.ContextIdApplicationContextInitializer,\
...

Aspect	ApplicationContextInitializer	ApplicationListener
Pattern	Initialization strategy (Template Method)	Observer
Main purpose	Configure / modify the context and environment	React to what's happening with the application
Timing	Exactly once: before refresh() (before beans are created)	Multiple times: at startup, at runtime, on shutdown
Access to beans	No (beans don't exist yet)	Yes (if you listen to later events or work inside a bean)
Typical example	Pull secrets from Vault into the Environment	Send a Telegram alert on ApplicationReadyEvent

3. Setting the primary sources

MyApplication.class is stored as primarySources — the root @Configuration class from which component scanning will start.

1.4. The Instance run() Method — a Step-by-Step Breakdown

Here is the skeleton of the run(String... args) method (Spring Boot 3.x):

public ConfigurableApplicationContext run(String... args) {
    // 1. Create the BootstrapContext
    DefaultBootstrapContext bootstrapContext = createBootstrapContext();
    ConfigurableApplicationContext context = null;

    // 2. Headless mode (java.awt.headless)
    configureHeadlessProperty();

    // 3. Get the run listeners
    SpringApplicationRunListeners listeners = getRunListeners(args);
    listeners.starting(bootstrapContext, this.mainApplicationClass);

    try {
        // 4. Prepare the Environment
        ApplicationArguments applicationArguments = new DefaultApplicationArguments(args);
        ConfigurableEnvironment environment = prepareEnvironment(listeners,
            bootstrapContext, applicationArguments);

        // 5. Print the banner
        Banner printedBanner = printBanner(environment);

        // 6. Create the ApplicationContext
        context = createApplicationContext();
        context.setApplicationStartup(this.applicationStartup);

        // 7. Prepare the context
        prepareContext(bootstrapContext, context, environment, listeners,
            applicationArguments, printedBanner);

        // 8. Refresh — the key stage
        refreshContext(context);

        // 9. afterRefresh (hook)
        afterRefresh(context, applicationArguments);

        // 10. Publish ApplicationStartedEvent
        listeners.started(context, timeTakenToStartup);

        // 11. Call ApplicationRunner / CommandLineRunner
        callRunners(context, applicationArguments);
    } catch (Throwable ex) {
        handleRunFailure(context, ex, listeners);
        throw new IllegalStateException(ex);
    }

    // 12. Publish ApplicationReadyEvent
    listeners.ready(context, timeTakenToReady);
    return context;
}

Step 1: DefaultBootstrapContext

BootstrapContext is a container for objects that are available before the ApplicationContext is created. It lives from the start of run() until the context is ready. It is used for registering early beans, such as the EnvironmentPostProcessor.

Step 2: configureHeadlessProperty()

private void configureHeadlessProperty() {
    System.setProperty(SYSTEM_PROPERTY_JAVA_AWT_HEADLESS,
        System.getProperty(SYSTEM_PROPERTY_JAVA_AWT_HEADLESS,
            Boolean.toString(this.headless)));
}

Sets java.awt.headless=true by default. This matters for server-side applications — it disables AWT GUI components.

Step 3: SpringApplicationRunListeners — the heart of the event mechanism

This is the SPI interface for startup lifecycle listeners:

public interface SpringApplicationRunListener {
    void starting(ConfigurableBootstrapContext bootstrapContext);
    void environmentPrepared(ConfigurableBootstrapContext bootstrapContext,
        ConfigurableEnvironment environment);
    void contextPrepared(ConfigurableApplicationContext context);
    void contextLoaded(ConfigurableApplicationContext context);
    void started(ConfigurableApplicationContext context, Duration timeTaken);
    void ready(ConfigurableApplicationContext context, Duration timeTaken);
    void failed(ConfigurableApplicationContext context, Throwable exception);
}

It is loaded via SpringFactoriesLoader from META-INF/spring.factories. Spring Boot ships a single implementation — EventPublishingRunListener.

EventPublishingRunListener is a bridge between SpringApplicationRunListener and ApplicationEvent. It translates every lifecycle callback into the corresponding event.

Callback	Event
`starting()`	ApplicationStartingEvent
`environmentPrepared()`	ApplicationEnvironmentPreparedEvent
`contextPrepared()`	ApplicationContextInitializedEvent
`contextLoaded()`	ApplicationPreparedEvent
`started()`	ApplicationStartedEvent
`ready()`	ApplicationReadyEvent
`failed()`	ApplicationFailedEvent

The complete sequence of events:

Event	When	Context available?
`ApplicationStartingEvent`	Before the Environment and Context exist	No
`ApplicationEnvironmentPreparedEvent`	Environment is ready, Context is not yet	No
`ApplicationContextInitializedEvent`	Context created, beans not yet loaded	Yes (empty)
`ApplicationPreparedEvent`	Beans loaded, `refresh()` not yet called	Yes (not refreshed)
`ApplicationStartedEvent`	`refresh()` done, runners not yet invoked	Yes (refreshed)
`AvailabilityChangeEvent` (Liveness)	Right after ApplicationStartedEvent	Yes
`ApplicationReadyEvent`	All runners have been executed	Yes (refreshed)
`AvailabilityChangeEvent` (Readiness)	Right after `ApplicationReadyEvent`	Yes
`ApplicationFailedEvent`	On any unhandled exception	Partially

Step 4: prepareEnvironment() — preparing the environment

private ConfigurableEnvironment prepareEnvironment(
        SpringApplicationRunListeners listeners,
        ConfigurableBootstrapContext bootstrapContext,
        ApplicationArguments applicationArguments) {

    // 1. Create or reuse the Environment
    ConfigurableEnvironment environment = getOrCreateEnvironment();

    // 2. Configure it: command line args, profiles
    configureEnvironment(environment, applicationArguments.getSourceArgs());

    // 3. Attach the ConfigurationPropertySources
    ConfigurationPropertySources.attach(environment);

    // 4. Publish ApplicationEnvironmentPreparedEvent
    listeners.environmentPrepared(bootstrapContext, environment);

    // 5. Bind spring.main.*
    DefaultPropertiesPropertySource.moveToEnd(environment);
    bindToSpringApplication(environment);

    // 6. Convert the Environment if necessary
    if (!this.isCustomEnvironment) {
        environment = convertEnvironment(environment);
    }

    ConfigurationPropertySources.attach(environment);
    return environment;
}

Key points:

getOrCreateEnvironment() — creates StandardServletEnvironment / StandardReactiveEnvironment / StandardEnvironment
configureEnvironment() — adds a CommandLinePropertySource and sets the active profiles
listeners.environmentPrepared() — this is where the EnvironmentPostProcessors kick in (e.g., loading application.yml)

Step 5: printBanner() — printing the banner

private Banner printBanner(ConfigurableEnvironment environment) {
    if (this.bannerMode == Banner.Mode.OFF) {
        return null;
    }
    ResourceLoader resourceLoader = (this.resourceLoader != null)
        ? this.resourceLoader : new DefaultResourceLoader(null);
    SpringApplicationBannerPrinter bannerPrinter = new SpringApplicationBannerPrinter(
        resourceLoader, this.banner);

    if (this.bannerMode == Banner.Mode.LOG) {
        return bannerPrinter.print(environment, this.mainApplicationClass, logger);
    }
    return bannerPrinter.print(environment, this.mainApplicationClass, System.out);
}

A banner.txt file in src/main/resources/ is picked up automatically
spring.banner.location — specify a custom file path
spring.main.banner-mode=off — disable the banner
Spring Boot 3.0.0 M2+: image banner support (PNG/JPEG/GIF) was removed; only banner.txt remains

Variables available in the banner: ${spring-boot.version}, ${application.version}, ${application.formatted-version}

Step 6: createApplicationContext() — choosing the context type

protected ConfigurableApplicationContext createApplicationContext() {
    return this.applicationContextFactory.create(this.webApplicationType);
}

Spring Boot 3 uses an ApplicationContextFactory (an enum-like factory):

ApplicationContextFactory DEFAULT = (webApplicationType) -> {
    try {
        switch (webApplicationType) {
            case SERVLET:
                return new AnnotationConfigServletWebServerApplicationContext();
            case REACTIVE:
                return new AnnotationConfigReactiveWebServerApplicationContext();
            default:
                return new AnnotationConfigApplicationContext();
        }
    } catch (Exception ex) {
        throw new IllegalStateException("Unable create a default ApplicationContext instance, "
            + "you may need a custom ApplicationContextFactory", ex);
    }
};

In Spring Boot 4, ApplicationContextFactory has been removed. Instead, a modular system is used — each module (spring-boot-webmvc, spring-boot-webflux) registers its own context via module dependencies. AbstractApplicationContextFactory is marked as @Deprecated(since="6.0", forRemoval=true).

Step 7: prepareContext() — preparing the context

private void prepareContext(DefaultBootstrapContext bootstrapContext,
        ConfigurableApplicationContext context,
        ConfigurableEnvironment environment,
        SpringApplicationRunListeners listeners,
        ApplicationArguments applicationArguments,
        Banner printedBanner) {

    // 1. Set the Environment
    context.setEnvironment(environment);

    // 2. postProcessApplicationContext (bean name generator, resource loader)
    postProcessApplicationContext(context);

    // 3. Apply the ApplicationContextInitializers
    applyInitializers(context);

    // 4. Publish ApplicationContextInitializedEvent
    listeners.contextPrepared(context);

    // 5. Register singleton beans: springApplicationArguments, springBootBanner
    if (this.logStartupInfo) {
        logStartupInfo(context.getParent() == null);
        logStartupProfileInfo(context);
    }
    ConfigurableListableBeanFactory beanFactory = context.getBeanFactory();
    beanFactory.registerSingleton("springApplicationArguments", applicationArguments);
    if (printedBanner != null) {
        beanFactory.registerSingleton("springBootBanner", printedBanner);
    }
    if (beanFactory instanceof DefaultListableBeanFactory dlbf) {
        dlbf.setAllowBeanDefinitionOverriding(this.allowBeanDefinitionOverriding);
    }
    if (this.lazyInitialization) {
        context.addBeanFactoryPostProcessor(
            new LazyInitializationBeanFactoryPostProcessor());
    }

    // 6. Load all the sources
    Set<Object> sources = getAllSources();
    load(context, sources.toArray(new Object[0]));

    // 7. Publish ApplicationPreparedEvent
    listeners.contextLoaded(context);
}

The key moment is applyInitializers(): this is where all ApplicationContextInitializers loaded from spring.factories get invoked. It's the mechanism for customizing the context before any beans are loaded.

Step 8: refreshContext() — starting the Spring container

private void refreshContext(ConfigurableApplicationContext context) {
    if (this.registerShutdownHook) {
        try {
            context.registerShutdownHook();
        } catch (AccessControlException ex) {
            // Not allowed in some environments
        }
    }
    refresh(context);
}

The refresh() method here is AbstractApplicationContext.refresh() from Spring Framework. This is where:

All singleton beans are created
BeanFactoryPostProcessors run → ConfigurationClassPostProcessorprocesses @Configuration
AutoConfigurationImportSelector runs → auto-configuration
BeanPostProcessors run
The embedded web server starts

Step 9: afterRefresh() — a hook

protected void afterRefresh(ConfigurableApplicationContext context,
        ApplicationArguments args) {
}

An empty hook meant to be overridden in subclasses.

Step 10: listeners.started() — ApplicationStartedEvent

ApplicationStartedEvent and AvailabilityChangeEvent(LivenessState.CORRECT) are published. From this moment on, the application is considered started, but it is not yet ready to serve traffic.

Step 11: callRunners() — ApplicationRunner and CommandLineRunner

private void callRunners(ApplicationContext context, ApplicationArguments args) {
    List<Object> runners = new ArrayList<>();
    runners.addAll(context.getBeansOfType(ApplicationRunner.class).values());
    runners.addAll(context.getBeansOfType(CommandLineRunner.class).values());
    AnnotationAwareOrderComparator.sort(runners);
    for (Object runner : new LinkedHashSet<>(runners)) {
        if (runner instanceof ApplicationRunner applicationRunner) {
            callRunner(applicationRunner, args);
        }
        if (runner instanceof CommandLineRunner commandLineRunner) {
            callRunner(commandLineRunner, args);
        }
    }
}

ApplicationRunner — receives ApplicationArguments (parsed)
CommandLineRunner — receives a raw String[]
They are sorted via @Order / Ordered

Step 12: listeners.ready() — ApplicationReadyEvent

ApplicationReadyEvent and AvailabilityChangeEvent(ReadinessState.ACCEPTING_TRAFFIC) are published. From this point on, the application is ready to accept traffic.

1.5. Error Handling — `handleRunFailure()`

private void handleRunFailure(ConfigurableApplicationContext context,
        Throwable exception, SpringApplicationRunListeners listeners) {
    try {
        try {
            handleExitCode(context, exception);
            if (listeners != null) {
                listeners.failed(context, exception);
            }
        } finally {
            reportFailure(getExceptionReporters(context), exception);
            if (context != null) {
                context.close();
            }
        }
    } catch (Exception ex) {
        logger.warn("Unable to close ApplicationContext", ex);
    }
    ReflectionUtils.rethrowRuntimeException(exception);
}

handleExitCode() — determines the exit code via ExitCodeExceptionMapper
listeners.failed() — publishes ApplicationFailedEvent
FailureAnalyzer — attempts to produce a human-readable description of the failure
The context is closed

1.6. Startup Sequence Diagram

main()
  │
  ├─ new SpringApplication(primarySource)
  │     ├─ deduceWebApplicationType()          → SERVLET / REACTIVE / NONE
  │     ├─ load SpringFactories (Initializers, Listeners)
  │     └─ set primarySources
  │
  └─ .run(args)
        │
        ├─ createBootstrapContext()
        ├─ configureHeadlessProperty()
        ├─ getRunListeners()                    → EventPublishingRunListener
        ├─ listeners.starting()                 → ApplicationStartingEvent
        │
        ├─ prepareEnvironment()
        │     ├─ getOrCreateEnvironment()       → StandardServletEnvironment
        │     ├─ configureEnvironment()         → CommandLinePropertySource, profiles
        │     ├─ ConfigurationPropertySources.attach()
        │     └─ listeners.environmentPrepared()→ ApplicationEnvironmentPreparedEvent
        │           └─ EnvironmentPostProcessor → ConfigDataEnvironmentPostProcessor
        │                 └─ loading application.yml/properties
        │
        ├─ printBanner()                        → banner.txt → System.out
        │
        ├─ createApplicationContext()
        │     └─ ApplicationContextFactory      → AnnotationConfigServletWebServerApplicationContext
        │
        ├─ prepareContext()
        │     ├─ setEnvironment()
        │     ├─ postProcessApplicationContext()
        │     ├─ applyInitializers()            → ApplicationContextInitializer
        │     ├─ listeners.contextPrepared()    → ApplicationContextInitializedEvent
        │     ├─ registerSingleton(springApplicationArguments)
        │     ├─ registerSingleton(springBootBanner)
        │     ├─ load(sources)                  → BeanDefinitionLoader
        │     └─ listeners.contextLoaded()      → ApplicationPreparedEvent
        │
        ├─ refreshContext()
        │     ├─ registerShutdownHook()
        │     └─ AbstractApplicationContext.refresh()
        │           ├─ invokeBeanFactoryPostProcessors()
        │           │     └─ ConfigurationClassPostProcessor → @Configuration, @Bean
        │           │     └─ AutoConfigurationImportSelector → auto-configuration
        │           ├─ registerBeanPostProcessors()
        │           ├─ initMessageSource()
        │           ├─ initApplicationEventMulticaster()
        │           ├─ onRefresh()
        │           │     └─ ServletWebServerApplicationContext.createWebServer()
        │           │           └─ TomcatServletWebServerFactory → Tomcat.start()
        │           └─ finishRefresh()
        │
        ├─ afterRefresh()                       → hook
        ├─ listeners.started()                  → ApplicationStartedEvent
        │                                          AvailabilityChangeEvent(Liveness)
        │
        ├─ callRunners()
        │     ├─ ApplicationRunner
        │     └─ CommandLineRunner
        │
        └─ listeners.ready()                    → ApplicationReadyEvent
                                                   AvailabilityChangeEvent(Readiness)

1.7. Spring Boot 3 vs Spring Boot 4 — Key Bootstrap Differences

Aspect	Spring Boot 3.x	Spring Boot 4.x
`ApplicationContextFactory`	Enum-like `DEFAULT` factory, picks a context based on `WebApplicationType`	Removed. The context is determined by module dependencies (`spring-boot-webmvc` / `spring-boot-webflux`)
`spring-boot-autoconfigure`	A single monolithic JAR (6.2 MB)	47 modular JARs, one per technology
Starters	`spring-boot-starter-web`	`spring-boot-starter-webmvc` (renamed)
`spring.factories`	SPI for auto-configuration	`META-INF/spring/...AutoConfiguration.imports` (already in 3.x, mandatory in 4.x)
Undertow	Supported	Removed (incompatible with Servlet 6.1)
Java baseline	Java 17+	Java 21+
Spring Framework	6.x	7.0
Jackson	Jackson 2.x	Jackson 3.x (namespace changes)
Banner (image)	PNG/JPEG/GIF removed since 3.0 M2	`banner.txt` only

Key Takeaways

SpringApplication.run() is a facade. All the real work happens in the instance run() method.
The SpringApplication constructor deduces the WebApplicationType from the classpath and loads the SPIs.
SpringApplicationRunListener is an extension point for hooking into the lifecycle. EventPublishingRunListener translates those calls into ApplicationEvents.
The Environment is prepared before the ApplicationContext — that's why EnvironmentPostProcessors can add property sources before any beans exist.
refreshContext() is the most important step. This is where all the beans are created, @Configuration classes are processed, and Tomcat/Netty starts.
ApplicationStartedEvent ≠ ApplicationReadyEvent. The former means the context is up; the latter means the runners have executed and the application is ready to accept traffic.
Spring Boot 4 is modular. ApplicationContextFactory is gone — the context is determined by your dependencies.

How to Build an HTTP/HTTPS + SOCKS5 Proxy in Go (with Logging, Metrics & Docker)

Silver_dev — Fri, 28 Aug 2026 21:04:39 +0000

I recently needed to build a proxy server, and Go was a natural choice for the job — its standard library and lightweight goroutines make network services a joy to write. In this post, I'll walk through the whole process step by step: from the first prototype to a Dockerized setup with logging and Prometheus metrics.

What We're Building

The proxy accepts two types of connections:

HTTP/HTTPS forward proxy — built on net/http and httputil.ReverseProxy (for regular requests), plus manual handling of the CONNECT method (for HTTPS tunnels).
SOCKS5 proxy — using the popular github.com/armon/go-socks5 library (golang.org/x/net/proxy is client-side only, so a server implementation would have to be written from scratch).

By the end, we'll have a single binary that runs both proxies, logs every request, exposes Prometheus metrics, and ships with a docker-compose.yml that brings up Prometheus and Grafana alongside it.

Prerequisites: a recent version of Go (1.25 was used here), curl for testing, and Docker if you want the containerized setup.

Step 1: The HTTP/HTTPS Forward Proxy

First, I sketched out the code for the HTTP/HTTPS forward proxy:

package main

import (
    "crypto/tls"
    "fmt"
    "io"
    "net"
    "net/http"
    "net/http/httputil"
    "net/url"
    "strings"
)

// HTTPProxy holds the proxy configuration (can be extended later)
type HTTPProxy struct {
    transport *http.Transport
}

// NewHTTPProxy creates a new proxy instance with a custom transport
func NewHTTPProxy() *HTTPProxy {
    return &HTTPProxy{
        transport: &http.Transport{
            // InsecureSkipVerify is for testing only — remove in production
            TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
            Proxy:           http.ProxyFromEnvironment,
        },
    }
}

// ServeHTTP implements http.Handler
func (p *HTTPProxy) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // If this is a CONNECT request, handle the HTTPS tunnel
    if r.Method == http.MethodConnect {
        p.handleTunnel(w, r)
        return
    }

    // For regular HTTP requests, use ReverseProxy
    p.handleHTTP(w, r)
}

// handleTunnel establishes a tunnel for CONNECT (HTTPS) requests
func (p *HTTPProxy) handleTunnel(w http.ResponseWriter, r *http.Request) {
    // Target host from the request (e.g., "example.com:443")
    target := r.Host
    if !strings.Contains(target, ":") {
        target += ":443" // default to 443 if no port is specified
    }

    // Connect to the target server
    destConn, err := net.Dial("tcp", target)
    if err != nil {
        http.Error(w, err.Error(), http.StatusServiceUnavailable)
        return
    }
    defer destConn.Close()

    // Reply to the client with "200 Connection Established"
    w.WriteHeader(http.StatusOK)
    hijacker, ok := w.(http.Hijacker)
    if !ok {
        http.Error(w, "Hijacking not supported", http.StatusInternalServerError)
        return
    }
    clientConn, _, err := hijacker.Hijack()
    if err != nil {
        http.Error(w, err.Error(), http.StatusServiceUnavailable)
        return
    }
    defer clientConn.Close()

    // Copy data in both directions (client <-> target server)
    go io.Copy(destConn, clientConn)
    io.Copy(clientConn, destConn)
}

// handleHTTP uses ReverseProxy for regular HTTP requests
func (p *HTTPProxy) handleHTTP(w http.ResponseWriter, r *http.Request) {
    // Build the target URL from the request.
    // For a forward proxy, the request URL contains the full address 
    //(e.g., http://example.com/foo)
    targetURL, err := url.Parse(r.URL.String())
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // If no scheme is specified, infer it from the port (usually 80)
    if targetURL.Scheme == "" {
        if r.URL.Port() == "443" {
            targetURL.Scheme = "https"
        } else {
            targetURL.Scheme = "http"
        }
    }

    // Create a ReverseProxy with a custom Director that rewrites the request
    proxy := &httputil.ReverseProxy{
        Director: func(req *http.Request) {
            // Forward to the target host
            req.URL.Scheme = targetURL.Scheme
            req.URL.Host = targetURL.Host
            req.URL.Path = targetURL.Path
            req.URL.RawQuery = targetURL.RawQuery
            req.Host = targetURL.Host // important for virtual hosts
            // Drop proxy-specific headers (if needed)
            req.Header.Del("Proxy-Connection")
        },
        Transport: p.transport,
    }

    // Serve the request
    proxy.ServeHTTP(w, r)
}

func main() {
    proxy := NewHTTPProxy()
    server := &http.Server{
        Addr:    ":8080",
        Handler: proxy,
    }

    fmt.Println("HTTP/HTTPS forward proxy is running on :8080")
    if err := server.ListenAndServe(); err != nil {
        fmt.Println("Error:", err)
    }
}

For CONNECT requests, the proxy hijacks the connection and pipes raw bytes in both directions, so the encrypted TLS session passes through untouched.

Step 2: The SOCKS5 Proxy

Next, the SOCKS5 proxy (using github.com/armon/go-socks5):

package main

import (
    "fmt"
    "log"
    "net"

    "github.com/armon/go-socks5"
)

func main() {
    // Create the SOCKS5 configuration (authentication, logging, etc. can be added here)
    conf := &socks5.Config{
        // You can plug in a custom Dialer here, e.g., to enforce restrictions
        // Logger: log.New(os.Stdout, "socks5: ", log.LstdFlags),
    }

    // Create the server
    server, err := socks5.New(conf)
    if err != nil {
        log.Fatalf("Failed to create SOCKS5 server: %v", err)
    }

    // Start listening on port 1080
    addr := ":1080"
    listener, err := net.Listen("tcp", addr)
    if err != nil {
        log.Fatalf("Failed to start listener: %v", err)
    }

    fmt.Printf("SOCKS5 proxy is running on %s\n", addr)
    if err := server.Serve(listener); err != nil {
        log.Fatalf("Server error: %v", err)
    }
}

Running and testing

Everything works nicely. Launch it with:

// The proxy will listen on http://localhost:8080
go run http_proxy.go

// The proxy will listen on socks5://localhost:1080
go run socks5_proxy.go

Testing it is straightforward:

# HTTP request
curl -x http://localhost:8080 http://example.com

# HTTPS request (via CONNECT)
curl -x http://localhost:8080 https://example.com

# SOCKS5 proxy
curl -x socks5://localhost:1080 https://example.com

Putting it all together

Now let's run both proxies from a single process. The project structure:

main.go
http_proxy.go
socks5_proxy.go

The entry point uses a cancellable context for graceful shutdown:

func main() {
    ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer cancel()

    g, ctx := errgroup.WithContext(ctx)

    g.Go(func() error { return runSocks5(ctx) })
    g.Go(func() error { return runHTTPProxy(ctx, ":8080") })

    if err := g.Wait(); err != nil && err != context.Canceled {
        log.Fatalf("Proxies stopped with an error: %v", err)
    }
    log.Println("Proxies shut down")
}

errgroup runs both proxies concurrently and tears everything down cleanly on SIGINT/SIGTERM.

Adding Logging

Great — now let's add logging for the SOCKS5 proxy. The go-socks5 library has built-in support for this: the Logger field in socks5.Config. You can pass in any logger that satisfies the expected interface — in practice, anything with a Printf method, such as *log.Logger (if you're on slog, wrap it with slog.NewLogLogger).

func runSocks5(ctx context.Context) error {
    // Create a logger with the desired prefix and flags
    logger := log.New(os.Stdout, "[SOCKS5] ", log.LstdFlags|log.Lshortfile)

    conf := &socks5.Config{
        Logger: logger, // Pass in the logger
    }
    server, err := socks5.New(conf)
    if err != nil {
        return fmt.Errorf("creating SOCKS5: %w", err)
    }

    // ... the rest of the code as before
}

And the same for the HTTP proxy:

func runHTTPProxy(ctx context.Context, addr string) error {
    proxy := NewHTTPProxy()
    logger := log.New(os.Stdout, "[HTTP] ", log.LstdFlags|log.Lshortfile)

    server := &http.Server{
        Addr:     addr,
        Handler:  proxy,
        ErrorLog: logger,
    }
    // ... the rest of the code as before
}

http.Server.ErrorLog covers server-level errors (TLS handshakes, Accept failures, panics), while socks5.Config.Logger logs protocol errors, authentication issues, and read/write failures.

Now let's log a bit more detail: the method, URL, and client IP. Add this to ServeHTTP

func (p *HTTPProxy) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // Log every request
    log.Printf("[HTTP] %s %s from %s", r.Method, r.URL.String(), r.RemoteAddr)

    if r.Method == http.MethodConnect {
        p.handleTunnel(w, r)
        return
    }
    p.handleHTTP(w, r)
}

One caveat: if your proxy runs behind a load balancer or another proxy, r.RemoteAddr will show the address of the previous hop. In that case, use the X-Forwarded-For header instead:

clientIP := r.Header.Get("X-Forwarded-For")
if clientIP == "" {
    clientIP = r.RemoteAddr
}
log.Printf("[HTTP] %s %s from %s", r.Method, r.URL.String(), clientIP)

Next, let's add proper middleware that logs the response status, processing time, and response size. For this we need a couple of wrapper types:

type loggingResponseWriter struct {
    http.ResponseWriter
    statusCode int
    size       int
}

func newLoggingResponseWriter(w http.ResponseWriter) *loggingResponseWriter {
    return &loggingResponseWriter{
        ResponseWriter: w,
        statusCode:     http.StatusOK, // default to 200 unless explicitly set
    }
}

func (lrw *loggingResponseWriter) WriteHeader(code int) {
    lrw.statusCode = code
    lrw.ResponseWriter.WriteHeader(code)
}

func (lrw *loggingResponseWriter) Write(b []byte) (int, error) {
    n, err := lrw.ResponseWriter.Write(b)
    lrw.size += n
    return n, err
}

// Hijack is required to support CONNECT tunnels
func (lrw *loggingResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
    if hijacker, ok := lrw.ResponseWriter.(http.Hijacker); ok {
        return hijacker.Hijack()
    }
    return nil, nil, fmt.Errorf("ResponseWriter does not support Hijack")
}

The final changes:

func (p *HTTPProxy) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    start := time.Now()

    // Wrap the ResponseWriter for logging
    lrw := newLoggingResponseWriter(w)

    // Handle the request through the existing methods
    if r.Method == http.MethodConnect {
        p.handleTunnel(lrw, r)
    } else {
        p.handleHTTP(lrw, r)
    }

    // Measure the duration and log it
    duration := time.Since(start)
    clientIP := r.RemoteAddr
    if forwarded := r.Header.Get("X-Forwarded-For"); forwarded != "" {
        clientIP = forwarded
    }
    // Use the standard log or your own logger
    log.Printf("[HTTP] %s %s from %s — status: %d, size: %d bytes, duration: %v",
        r.Method, r.URL.String(), clientIP, lrw.statusCode, lrw.size, duration)
}

Sample output:

[HTTP] GET http://detectportal.firefox.com/canonical.html from 127.0.0.1:12495 — status: 200, size: 90 bytes, duration: 157.5029ms
[HTTP] GET http://detectportal.firefox.com/success.txt?ipv4 from 127.0.0.1:12497 — status: 200, size: 8 bytes, duration: 143.6892ms
[HTTP] GET http://detectportal.firefox.com/success.txt?ipv6 from 127.0.0.1:12498 — status: 200, size: 8 bytes, duration: 151.2498ms

Let's add similar logging for SOCKS5, so we can see the command (CONNECT, BIND, UDP), the target address, the client IP, the session duration, and the status (success/failure).

Here's what we add:

type loggingListener struct {
    net.Listener
    logger *log.Logger
}

func (l loggingListener) Accept() (net.Conn, error) {
    conn, err := l.Listener.Accept()
    if err != nil {
        return nil, err
    }
    clientAddr := conn.RemoteAddr().String()
    l.logger.Printf("Accepted connection from %s", clientAddr)
    // Store the start time in the wrapper
    return &loggingConn{
        Conn:       conn,
        logger:     l.logger,
        clientAddr: clientAddr,
        startTime:  time.Now(),
    }, nil
}

type loggingConn struct {
    net.Conn
    logger     *log.Logger
    clientAddr string
    startTime  time.Time
}

func (c *loggingConn) Close() error {
    err := c.Conn.Close()
    duration := time.Since(c.startTime)
    c.logger.Printf("Connection from %s closed, total duration: %v", c.clientAddr, duration)
    return err
}

And the full runSocks5 with logging wired in:

func runSocks5(ctx context.Context) error {
    logger := log.New(os.Stdout, "[SOCKS5] ", log.LstdFlags)

    rawListener, err := net.Listen("tcp", ":1080")
    if err != nil {
        return fmt.Errorf("SOCKS5 listener: %w", err)
    }

    // Logging listener
    listener := loggingListener{
        Listener: rawListener,
        logger:   logger,
    }

    conf := &socks5.Config{
        Logger: logger,
        Dial: func(ctx context.Context, network, addr string) (net.Conn, error) {
            // Log the target address and connection setup time
            start := time.Now()
            conn, err := net.Dial(network, addr)
            duration := time.Since(start)
            if err != nil {
                logger.Printf("Dial to %s failed: %v (duration: %v)", addr, err, duration)
                return nil, err
            }
            logger.Printf("Dial to %s succeeded (duration: %v)", addr, duration)
            return conn, nil
        },
    }

    server, err := socks5.New(conf)
    if err != nil {
        return fmt.Errorf("creating SOCKS5: %w", err)
    }

    errCh := make(chan error, 1)
    go func() {
        errCh <- server.Serve(listener)
    }()

    logger.Printf("SOCKS5 is running on :1080")

    select {
    case <-ctx.Done():
        rawListener.Close()
        <-errCh
        logger.Printf("SOCKS5 stopped")
        return ctx.Err()
    case err := <-errCh:
        return err
    }
}

Sample output:

[SOCKS5] 2025/03/15 12:34:56 Accepted connection from 192.168.1.100:54321
[SOCKS5] 2025/03/15 12:34:56 Dial to 2.23.167.41:443 succeeded (duration: 40.6345ms)
[SOCKS5] 2025/03/15 12:35:10 Connection from 192.168.1.100:54321 closed, total duration: 14s

Adding metrics

Let's add a /metrics endpoint with a single metric — the number of active TCP connections (covering both HTTP and SOCKS5). That gives us basic load monitoring. We'll create a metrics.go file and add github.com/prometheus/client_golang to the project.

In metrics.go:

import (
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promhttp"
    "net"
    "sync/atomic"
)

var (
    activeConnections = prometheus.NewGauge(prometheus.GaugeOpts{
        Name: "proxy_active_connections",
        Help: "Current number of active TCP connections",
    })
)

func init() {
    prometheus.MustRegister(activeConnections)
}

// metricsListener is a wrapper that counts active connections
type metricsListener struct {
    net.Listener
}

func (ml metricsListener) Accept() (net.Conn, error) {
    conn, err := ml.Listener.Accept()
    if err != nil {
        return nil, err
    }
    activeConnections.Inc()
    return &metricsConn{Conn: conn}, nil
}

type metricsConn struct {
    net.Conn
}

func (mc *metricsConn) Close() error {
    err := mc.Conn.Close()
    activeConnections.Dec()
    return err
}

func runMetrics(ctx context.Context) error {
    mux := http.NewServeMux()
    mux.Handle("/metrics", promhttp.Handler())
    server := &http.Server{
        Addr:    ":9090",
        Handler: mux,
    }

    errCh := make(chan error, 1)
    go func() {
        errCh <- server.ListenAndServe()
    }()

    select {
    case <-ctx.Done():
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        server.Shutdown(shutdownCtx)
        return ctx.Err()
    case err := <-errCh:
        return err
    }
}

Integrating into runHTTPProxy:

func runHTTPProxy(ctx context.Context, addr string) error {
    logger := log.New(os.Stdout, "[HTTP] ", log.LstdFlags)

    rawListener, err := net.Listen("tcp", addr)
    if err != nil {
        return err
    }
    listener := metricsListener{Listener: rawListener}

    proxy := NewHTTPProxy()
    server := &http.Server{
        Handler:  proxy,
        ErrorLog: logger,
    }

    errCh := make(chan error, 1)
    go func() {
        errCh <- server.Serve(listener)
    }()

    select {
    case <-ctx.Done():
        // graceful shutdown
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        server.Shutdown(shutdownCtx)
        return ctx.Err()
    case err := <-errCh:
        return err
    }
}

Integrating into runSocks5 — here we also use metricsListener instead of loggingListener:

func runSocks5(ctx context.Context) error {
    logger := log.New(os.Stdout, "[SOCKS5] ", log.LstdFlags)

    rawListener, err := net.Listen("tcp", ":1080")
    if err != nil {
        return err
    }

    listener := metricsListener{Listener: rawListener}

    conf := &socks5.Config{
        Logger: logger,
        Dial: func(ctx context.Context, network, addr string) (net.Conn, error) {
            // Log the target address and connection setup time
            start := time.Now()
            conn, err := net.Dial(network, addr)
            duration := time.Since(start)
            if err != nil {
                logger.Printf("Dial to %s failed: %v (duration: %v)", addr, err, duration)
                return nil, err
            }
            logger.Printf("Dial to %s succeeded (duration: %v)", addr, duration)
            return conn, nil
        },
    }

    server, err := socks5.New(conf)
    if err != nil {
        return err
    }

    errCh := make(chan error, 1)
    go func() {
        errCh <- server.Serve(listener)
    }()

    select {
    case <-ctx.Done():
        rawListener.Close()
        <-errCh
        logger.Printf("SOCKS5 stopped")
        return ctx.Err()
    case err := <-errCh:
        return err
    }
}

And the /metrics server itself:

func runMetrics(ctx context.Context) error {
    mux := http.NewServeMux()
    mux.Handle("/metrics", promhttp.Handler())
    server := &http.Server{
        Addr:    ":9090",
        Handler: mux,
    }

    errCh := make(chan error, 1)
    go func() {
        errCh <- server.ListenAndServe()
    }()

    select {
    case <-ctx.Done():
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        server.Shutdown(shutdownCtx)
        return ctx.Err()
    case err := <-errCh:
        return err
    }
}

We add a third goroutine in main:

g.Go(func() error { return runMetrics(ctx) })

Containerizing with Docker

The last piece is the Dockerfile:

FROM golang:1.25-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go build -o proxy .

FROM alpine:latest
RUN apk --no-cache add ca-certificates && \
    addgroup -S appgroup && \
    adduser -S appuser -G appgroup

WORKDIR /app
COPY --from=builder /app/proxy .
RUN chown appuser:appgroup /app/proxy && chmod 755 /app/proxy

EXPOSE 8080 1080 9090

USER appuser

CMD ["./proxy"]

And a docker-compose.yml that brings up the proxy alongside Prometheus and Grafana:

version: '3.8'

services:
  proxy:
    build: .
    container_name: go-proxy
    ports:
      - "8080:8080"   # HTTP proxy
      - "1080:1080"   # SOCKS5
      - "9090:9090"   # metrics
    restart: unless-stopped
    networks:
      - monitoring

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    ports:
      - "9091:9090"   # We forward it to a different port to avoid conflicts with proxy metrics.
    restart: unless-stopped
    networks:
      - monitoring
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    volumes:
      - ./grafana/provisioning:/etc/grafana/provisioning:ro
      - grafana_data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    ports:
      - "3000:3000"
    restart: unless-stopped
    networks:
      - monitoring

networks:
  monitoring:

volumes:
  prometheus_data:
  grafana_data:

Final files:

main.go:

func main() {
    ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer cancel()

    g, ctx := errgroup.WithContext(ctx)

    g.Go(func() error { return runSocks5(ctx) })
    g.Go(func() error { return runHTTPProxy(ctx, ":8080") })
    g.Go(func() error { return runMetrics(ctx) })

    if err := g.Wait(); err != nil && err != context.Canceled {
        log.Fatalf("Proxies stopped with an error: %v", err)
    }
    log.Println("Proxies shut down")
}

http_proxy.go:

type loggingResponseWriter struct {
    http.ResponseWriter
    statusCode int
    size       int
}

func newLoggingResponseWriter(w http.ResponseWriter) *loggingResponseWriter {
    return &loggingResponseWriter{
        ResponseWriter: w,
        statusCode:     http.StatusOK,
    }
}

func (lrw *loggingResponseWriter) WriteHeader(code int) {
    lrw.statusCode = code
    lrw.ResponseWriter.WriteHeader(code)
}

func (lrw *loggingResponseWriter) Write(b []byte) (int, error) {
    n, err := lrw.ResponseWriter.Write(b)
    lrw.size += n
    return n, err
}

func (lrw *loggingResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
    if hijacker, ok := lrw.ResponseWriter.(http.Hijacker); ok {
        return hijacker.Hijack()
    }
    return nil, nil, fmt.Errorf("ResponseWriter does not support Hijack")
}

type HTTPProxy struct {
    transport *http.Transport
}

func NewHTTPProxy() *HTTPProxy {
    return &HTTPProxy{
        transport: &http.Transport{
            TLSClientConfig: &tls.Config{},
            Proxy:           http.ProxyFromEnvironment,
        },
    }
}

func (p *HTTPProxy) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    start := time.Now()

    lrw := newLoggingResponseWriter(w)

    if r.Method == http.MethodConnect {
        p.handleTunnel(lrw, r)
    } else {
        p.handleHTTP(lrw, r)
    }

    duration := time.Since(start)
    clientIP := r.RemoteAddr
    if forwarded := r.Header.Get("X-Forwarded-For"); forwarded != "" {
        clientIP = forwarded
    }
    log.Printf("[HTTP] %s %s from %s — status: %d, size: %d bytes, duration: %v",
        r.Method, r.URL.String(), clientIP, lrw.statusCode, lrw.size, duration)
}

func (p *HTTPProxy) handleTunnel(w http.ResponseWriter, r *http.Request) {
    target := r.Host
    if !strings.Contains(target, ":") {
        target += ":443" // default to 443 if no port is specified
    }

    destConn, err := net.Dial("tcp", target)
    if err != nil {
        http.Error(w, err.Error(), http.StatusServiceUnavailable)
        return
    }
    defer destConn.Close()

    w.WriteHeader(http.StatusOK)
    hijacker, ok := w.(http.Hijacker)
    if !ok {
        http.Error(w, "Hijacking not supported", http.StatusInternalServerError)
        return
    }
    clientConn, _, err := hijacker.Hijack()
    if err != nil {
        http.Error(w, err.Error(), http.StatusServiceUnavailable)
        return
    }
    defer clientConn.Close()

    go io.Copy(destConn, clientConn)
    io.Copy(clientConn, destConn)
}

func (p *HTTPProxy) handleHTTP(w http.ResponseWriter, r *http.Request) {
    targetURL, err := url.Parse(r.URL.String())
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    if targetURL.Scheme == "" {
        if r.URL.Port() == "443" {
            targetURL.Scheme = "https"
        } else {
            targetURL.Scheme = "http"
        }
    }

    proxy := &httputil.ReverseProxy{
        Director: func(req *http.Request) {
            req.URL.Scheme = targetURL.Scheme
            req.URL.Host = targetURL.Host
            req.URL.Path = targetURL.Path
            req.URL.RawQuery = targetURL.RawQuery
            req.Host = targetURL.Host
            req.Header.Del("Proxy-Connection")
        },
        Transport: p.transport,
    }

    proxy.ServeHTTP(w, r)
}

func runHTTPProxy(ctx context.Context, addr string) error {
    logger := log.New(os.Stdout, "[HTTP] ", log.LstdFlags)

    rawListener, err := net.Listen("tcp", addr)
    if err != nil {
        return err
    }
    listener := metricsListener{Listener: rawListener}

    proxy := NewHTTPProxy()
    server := &http.Server{
        Handler:  proxy,
        ErrorLog: logger,
    }

    errCh := make(chan error, 1)
    go func() {
        errCh <- server.Serve(listener)
    }()

    select {
    case <-ctx.Done():
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        server.Shutdown(shutdownCtx)
        return ctx.Err()
    case err := <-errCh:
        return err
    }
}

socks5_proxy.go:

type contextKey string

const (
    startTimeKey  contextKey = "start_time"
    clientAddrKey contextKey = "client_addr"
    cmdKey        contextKey = "command"
)

type loggingListener struct {
    net.Listener
    logger *log.Logger
}

func (l loggingListener) Accept() (net.Conn, error) {
    conn, err := l.Listener.Accept()
    if err != nil {
        return nil, err
    }

    clientAddr := conn.RemoteAddr().String()
    l.logger.Printf("Accepted connection from %s", clientAddr)

    ctx := context.WithValue(context.Background(), startTimeKey, time.Now())
    ctx = context.WithValue(ctx, clientAddrKey, clientAddr)

    return &loggingConn{
        Conn:   conn,
        ctx:    ctx,
        logger: l.logger,
    }, nil
}

type loggingConn struct {
    net.Conn
    ctx    context.Context
    logger *log.Logger
}

func (c *loggingConn) Close() error {
    err := c.Conn.Close()
    start, ok := c.ctx.Value(startTimeKey).(time.Time)
    if ok {
        duration := time.Since(start)
        clientAddr, _ := c.ctx.Value(clientAddrKey).(string)
        c.logger.Printf("Connection closed from %s, duration: %v", clientAddr, duration)
    }
    return err
}

func runSocks5(ctx context.Context) error {
    logger := log.New(os.Stdout, "[SOCKS5] ", log.LstdFlags)

    rawListener, err := net.Listen("tcp", ":1080")
    if err != nil {
        return err
    }

    listener := metricsListener{Listener: rawListener}

    conf := &socks5.Config{
        Logger: logger,
        Dial: func(ctx context.Context, network, addr string) (net.Conn, error) {
            start := time.Now()
            conn, err := net.Dial(network, addr)
            duration := time.Since(start)
            if err != nil {
                logger.Printf("Dial to %s failed: %v (duration: %v)", addr, err, duration)
                return nil, err
            }
            logger.Printf("Dial to %s succeeded (duration: %v)", addr, duration)
            return conn, nil
        },
    }

    server, err := socks5.New(conf)
    if err != nil {
        return err
    }

    errCh := make(chan error, 1)
    go func() {
        errCh <- server.Serve(listener)
    }()

    select {
    case <-ctx.Done():
        rawListener.Close()
        <-errCh
        logger.Printf("SOCKS5 stopped")
        return ctx.Err()
    case err := <-errCh:
        return err
    }
}

metrics.go:

var (
    activeConnections = prometheus.NewGauge(prometheus.GaugeOpts{
        Name: "proxy_active_connections",
        Help: "Current number of active TCP connections",
    })
)

func init() {
    prometheus.MustRegister(activeConnections)
}

type metricsListener struct {
    net.Listener
}

func (ml metricsListener) Accept() (net.Conn, error) {
    conn, err := ml.Listener.Accept()
    if err != nil {
        return nil, err
    }
    activeConnections.Inc()
    return &metricsConn{Conn: conn}, nil
}

type metricsConn struct {
    net.Conn
}

func (mc *metricsConn) Close() error {
    err := mc.Conn.Close()
    activeConnections.Dec()
    return err
}

func runMetrics(ctx context.Context) error {
    mux := http.NewServeMux()
    mux.Handle("/metrics", promhttp.Handler())
    server := &http.Server{
        Addr:    ":9090",
        Handler: mux,
    }

    errCh := make(chan error, 1)
    go func() {
        errCh <- server.ListenAndServe()
    }()

    select {
    case <-ctx.Done():
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        server.Shutdown(shutdownCtx)
        return ctx.Err()
    case err := <-errCh:
        return err
    }
}

Java Virtual Threads

Silver_dev — Thu, 04 Jun 2026 20:38:48 +0000

Java Virtual Threads Model

In short:

VirtualThread (lightweight thread) — the code
      ↓
ForkJoinPool (scheduler)
      ↓
Carrier Thread (regular platform thread = OS thread)
      ↓
Mount/Unmount mechanism (mounted/unmounted)

ForkJoinPool is a pool of carrier threads. It is the one that decides which carrier thread will pick up the next virtual thread.

VirtualThread blocks (I/O, socket)
→ Detected via the JDK mechanism (re-implemented operations)
→ VirtualThread UNMOUNTS from the Carrier Thread
→ Continuation is saved (stack + state)
→ Carrier Thread starts executing ANOTHER VirtualThread from the queue
→ When I/O completes → the virtual thread is placed back into the ready queue

In detail:

Task scheduling: The scheduler (ForkJoinPool) does not dispatch a VirtualThread abstractly; it creates a task (Runnable) to execute this virtual thread's code and places it into the queue of a specific Carrier Thread. This is what scheduling is.
Carrier's local queue: Yes, each Carrier Thread in the ForkJoinPool has its own queue — Deque<Runnable>. This is a key detail for Work-Stealing: when a thread becomes free, it checks its own queue first, and if it's empty, it tries to "steal" a task from another thread's queue.
Task execution:
- The Carrier Thread takes a task from its queue.
- This task is nothing else but the virtual thread's code.
- As soon as the Carrier starts executing this task, Mounting occurs — the virtual thread's state (its stack) is placed onto the actual stack of the Carrier Thread.
Unmounting as a context switch:
- When the virtual thread performs a blocking operation, unmount() is called.
- The Carrier Thread immediately saves the current stack state of the virtual thread to the Heap.
- Then, instead of waiting for the operation to complete, the Carrier grabs the next task from its queue (or steals from a neighbor) and mounts a new virtual thread onto itself.
- The original virtual thread itself transitions to a waiting state. Once the I/O completes, it will be placed back into the queue of some Carrier Thread (possibly a different one) for re-mounting and resumption of work.

Java Virtual Threads use preemptive scheduling only at blocking points (I/O, synchronized, etc.). If a thread is busy with pure computations (CPU-bound), it will monopolize the carrier thread and will not be preempted until completion or forced blocking. If your code runs a loop for 10 seconds — it will occupy the carrier for the entire time. An infinite loop without I/O will pin (block) the carrier thread.

This is due to the fact that virtual threads in Java were designed primarily for highly loaded I/O-bound servers (spending 80-90% of the time waiting). For CPU-bound tasks inside virtual threads, it is recommended to either avoid them or insert artificial yield points, such as Thread.sleep(1) or Thread.yield(), to give other threads a chance to execute.

Virtual Thread

Let's trace the complete lifecycle of a Virtual Thread in Java from the moment of its creation until it is garbage collected.

Virtual Thread Creation

At this stage, the VirtualThread Java object is created. The JVM does not allocate a separate OS stack for it and does not bind it to any OS thread. Instead, the JVM allocates a small Continuation object in the heap, which will store the virtual thread's stack state when it is not executing. The initial size of this state is only a few hundred bytes.

There are several ways to create a virtual thread:

Thread.startVirtualThread(Runnable task): Creates and immediately starts a new virtual thread. This is the simplest way for one-off tasks.
Thread.ofVirtual().start(Runnable task): A more flexible approach using a Builder, allowing you to set the thread name, uncaught exception handler, and other parameters before starting.
Executors.newVirtualThreadPerTaskExecutor(): Creates an ExecutorService that spawns a new virtual thread for each task. This is the recommended way for server applications, as it allows easy management of a massive number of tasks.

Starting and Scheduling (State: NEW -> RUNNABLE)

When the .start() method is called, the virtual thread is not executed immediately. It is marked as ready for execution (RUNNABLE), and the JVM places it into the scheduler's queue. The virtual thread scheduler in Java is implemented on top of a ForkJoinPool. This pool operates on the work-stealing principle: each Carrier Thread has its own task queue, and if one thread finishes its tasks, it can "steal" a task from another thread's queue, which ensures high CPU core utilization.

The virtual thread's task is now ready to be executed. However, at this point, it is not yet bound to any OS thread.

Mounting onto a Carrier Thread (Mounting)

When one of the ForkJoinPool threads (which acts as the Carrier Thread — a regular OS platform thread) becomes free, it picks a ready virtual thread from the queue and mounts it onto itself.

The mounting process involves:

Mount/Unmount scheme: Essentially, the JVM finds a free platform thread to "put" the virtual thread onto for execution.
State restoration (Thawing): The JVM retrieves the previously saved virtual thread stack (the Continuation object) from the heap and "thaws" it, transferring it to the actual stack of the carrier thread.
Execution start: After this, the code inside the virtual thread begins to execute.

The virtual thread is now in the RUNNING state.

Execution and Blocking Operations

While the virtual thread code is executing computations, everything works just like with a regular thread. The magic happens at the moment of a blocking operation (e.g., waiting for a database response, calling Thread.sleep(), reading from a socket). At this point, the key mechanism of virtual threads triggers — unmounting:

Blocking detection: The JVM intercepts the blocking method call.
Freezing: The JVM saves the current execution stack state of the virtual thread (all local variables, program counter, etc.) into a special Continuation object in the heap and "freezes" it.
Carrier release: The virtual thread unmounts from its carrier thread. The carrier thread is no longer busy and returns to the ForkJoinPool, ready to execute the next virtual task.
Transition to PARKING state: The virtual thread itself transitions to the PARKING (waiting) state.

It is important to note that during its lifetime, a virtual thread can be mounted on different carrier threads. Right after waking up, it might end up on a completely different Carrier Thread from the pool.

Special Case: Pinning

In some cases, a virtual thread cannot be unmounted during a blocking operation and is forced to wait, occupying the carrier thread. This is called pinning. This happens under the following conditions:

Inside a synchronized block or method: Acquiring a synchronized monitor pins the virtual thread to the carrier.
When executing a native method (JNI) or foreign function: The JVM cannot safely "freeze" a native stack.

Such behavior can significantly reduce scalability since the carrier thread gets blocked. Fortunately, in Java 24, this issue was resolved as part of JEP 491: Synchronize Virtual Threads without Pinning. In newer versions, synchronized no longer causes pinning; this became possible thanks to internal optimizations that allow virtual threads to correctly unmount even inside synchronized blocks.

To find problematic spots in code on Java 21, you can use the flag
-Djdk.tracePinnedThreads=full

Waking Up and Resuming (Unparking)

When the operation on which the virtual thread was blocked completes (e.g., a DB response arrives), the wake-up mechanism triggers:

Readiness signal: The JVM receives a notification that the resource has become available.
Unparking: The JVM transitions the virtual thread from the PARKING state to the RUNNABLE state (ready to execute).
Enqueuing: The JVM places the Continuation of this woken thread back into the ForkJoinPool queue for scheduling.
Re-mounting: As soon as one of the pool's carrier threads becomes free, it "thaws" the Continuation and mounts the virtual thread to resume execution, possibly on a different carrier.

Thus, while the virtual thread was waiting for a DB response for 2 seconds, the carrier thread on which it was originally executing managed to process thousands of other virtual tasks, which drastically increases the overall throughput of the application.

Termination and Disposal (Garbage Collection)

A virtual thread can terminate naturally when the run() method of its task completes, or forcibly if the interrupt() method is called during waiting or execution. After the thread terminates:

The virtual thread transitions to the TERMINATED state.
Its association with the Continuation object is broken.
Garbage Collection: The thread object itself and its Continuation (the heap-allocated stack) no longer have strong references from GC Roots (e.g., from the ForkJoinPool). Therefore, during the next garbage collection cycle, they can be collected.
Crucial difference from regular threads: A virtual thread's stack is stored in the heap and is not a GC root. This is a critically important optimization: creating and destroying millions of virtual threads does not create a massive load on the garbage collector, since their stacks do not need to be scanned every time during collection.

Takeaways

Thanks to storing the stack in the heap, you can create millions of virtual threads that collectively will occupy significantly less memory than a few thousand standard threads.
Do not pool virtual threads: Creating a virtual thread is a very cheap operation. They do not need to be cached, as was the case with platform threads. On the contrary, create a new thread for each task.
Be careful with ThreadLocal: If you still use ThreadLocal with virtual threads, remember that they live exactly as long as the virtual thread lives. A virtual thread pool is an anti-pattern, so an object pool via ThreadLocal also becomes meaningless and can lead to memory leaks. As a modern alternative for context propagation, you can use ScopedValue.
Track Pinning: On Java 21, use -Djdk.tracePinnedThreads to identify places where virtual threads are pinned to the carrier. This will help ensure you are getting the maximum benefit from using them.

Differences between Java and Golang in working with HashMap, map, ArrayList, and slice

Silver_dev — Mon, 01 Jun 2026 20:49:30 +0000

ArrayList vs slice

Data Structure

A Slice in Go is a three-component structure (24 bytes on a 64-bit system):

type slice struct {
    array unsafe.Pointer // pointer to the underlying array in the heap (8 bytes)
    len   int            // length (8 bytes)
    cap   int            // capacity (8 bytes)
}

An ArrayList in Java is a single object containing:

class ArrayList<E> {
    private transient Object[] elementData;  // reference to an array
    private int size;                        // size
    // capacity = elementData.length
    // There is no separate cap field — it is derived from elementData.length
}

If new ArrayList<>(5), then:

An internal Object[5] array is created
size = 0 (how many elements are actually added)
capacity = 5 (the maximum before the next resize)

Passing to Functions

// Java — passes an object reference (8 bytes on 64-bit)
void modify(ArrayList<Integer> list) {
    list.set(0, 100);              // modifies the original
    list.add(200);                 // modifies the original
}

// Go — copies the slice header (fast, 24 bytes)
func modify(s []int) {
    s[0] = 100          // modifies the original (shared underlying array)
    s = append(s, 200)  // does NOT modify the original's len/cap
}

In Go, passing a slice is cheap (copying 24 bytes)
However, append might not be reflected in the calling function
In Java, passing is cheap (1 reference), and you always operate on the original object

Resizing (Reallocation)

Java (ArrayList):

ArrayList<Integer> list = new ArrayList<>(5); // capacity=5
for(int i=0; i<5; i++) list.add(i);           // no reallocation
list.add(5);  // capacity = 5 + (5 >> 1) = 7 (increase 50%)
// The old array becomes garbage (eligible for GC)

Go (slice):

s := make([]int, 0, 5)  // cap=5
s = append(s, 1,2,3,4,5) // cap=5, no reallocation
s = append(s, 6)         // cap=10 (typically *2 for <1024, then +25%)
// The old array (cap 5) becomes garbage (collected by GC)

Growth Algorithms:

Go: roughly cap = cap * 2 for small sizes, cap = cap + cap/4 for large sizes
Java: newCapacity = oldCapacity + (oldCapacity >> 1) (1.5x)

Zeroing Out vs Retaining References

Java (on reallocation):

ArrayList<String> list = new ArrayList<>(3);
list.add("a"); list.add("b"); list.add("c");
list.add("d");  // copies references to the new array
// Old objects are NOT zeroed out, but the old array is GC'd

Go (on reallocation):

s := make([]int, 3, 3)  // [0,0,0]
s = append(s, 1)        // new array, the old one is zeroed

Interesting nuances:

Go:

func smallSlice() []int {
    s := make([]int, 3, 3)   // May stay on the stack if it does not escape
    return s                 // Escapes to the heap
}

Java:

The ArrayList object is always on the heap
But the JVM can perform scalar replacement (stack allocation) for small objects

Go:

// Go: must remember to return
func addToSlice(s []int, val int) []int {
    return append(s, val)  // must return the new slice
}

// Otherwise:
func brokenAdd(s []int, val int) {
    s = append(s, val)  // BUG: won't modify the original
}

Java:

// Java: always works correctly
void addToList(ArrayList<Integer> list, int value) {
    list.add(value);  // always modifies the original
}

subList() — returns a view (not a copy):

ArrayList<Integer> list = new ArrayList<>(List.of(1,2,3,4,5));
List<Integer> sub = list.subList(1, 4);  // [2,3,4]
sub.set(0, 100);   // modifies the original: list = [1,100,3,4,5]
sub.add(999);      // also modifies the list

// DANGEROUS: upon structural modification of the original, the sub-list becomes invalid
list.add(6);       // sub now throws ConcurrentModificationException

removeRange() — a protected method

public class MyArrayList<T> extends ArrayList<T> {
    public void removeRangePublic(int from, int to) {
        super.removeRange(from, to);  // removes without creating garbage
    }
}

// Before: size=10, capacity=20
list.removeRange(2, 5);  // removed 3 elements

// After: size=7, capacity=20 (unchanged)

size decreases by the number of removed elements.
capacity does not change.

What happens internally:

protected void removeRange(int fromIndex, int toIndex) {
    int numMoved = size - toIndex;
    System.arraycopy(elementData, toIndex, elementData, fromIndex, numMoved);
    size = fromIndex + numMoved;  // only size decreases
    // elementData.length (capacity) remains the same
}

trimToSize() — trims the capacity down to the current size

ArrayList<String> list = new ArrayList<>(1000);
// ... added only 10 elements
list.trimToSize();  // elementData = new Object[10], saving memory

ArrayList.get(index) runs in O(1) time, just like a slice in Go.

// ArrayList.get() - direct access by index
public E get(int index) {
    return (E) elementData[index];  // constant time
}

// But LinkedList.get() is O(n)
LinkedList<String> linked = new LinkedList<>();
linked.get(1000);  // need to traverse 1000 nodes

Synchronized variant
В Go:

type SafeSlice struct {
    mu sync.RWMutex
    slice []int
}

func (s *SafeSlice) Add(val int) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.slice = append(s.slice, val)
}

func (s *SafeSlice) Get(i int) int {
    s.mu.RLock()
    defer s.mu.RUnlock()
    return s.slice[i]
}

Java:

// Regular ArrayList is not thread-safe
List<String> list = new ArrayList<>();
list.add("a");  // unsynchronized

// Synchronized wrapper
List<String> syncList = Collections.synchronizedList(new ArrayList<>());

// MUST synchronize when iterating
synchronized (syncList) {
    for (String s : syncList) {  // manual sync is required
        // ...
    }
}

// ConcurrentModificationException IS POSSIBLE even in a synchronizedList

Memory visibility (volatile vs sync/atomic)

Go:

type Data struct {
    mu sync.Mutex
    slice []int
}

func (d *Data) Add(val int) {
    d.mu.Lock()
    defer d.mu.Unlock()
    d.slice = append(d.slice, val)  // mutex guarantees visibility
}

// Without a mutex - data race:
func (d *Data) BrokenAdd(val int) {
    d.slice = append(d.slice, val)  // data race
}

Java:

class SharedData {
    private volatile ArrayList<String> list;  // volatile for the reference

    public void update() {
        list = new ArrayList<>();  // reference change is visible to all threads
    }

    public void addElement(String s) {
        // Bad: volatile does not protect the elements
        list.add(s);  // might not be visible to other threads
    }

    // Correct approach:
    public synchronized void addSafe(String s) {
        list.add(s);  // synchronized guarantees visibility
    }
}

HashMap vs map

Typing

// Java - type-safe, but via generics
HashMap<String, Integer> map = new HashMap<>();
map.put("key", 123);

// Go - strict typing at the compiler level
m := make(map[string]int)
m["key"] = 123

nil vs null

// Java
HashMap<String, String> map = null;  // allowed, but NullPointerException upon usage
map.put("key", "value");  // NullPointerException
// Cannot call methods on a null reference

map = new HashMap<>();
map.put(null, "value");  // null key is allowed

// Go
var m map[string]string   // nil map
m["key"] = "value"        // panic: assignment to entry in nil map

m = make(map[string]string)  // must be initialized
m["key"] = "value"           // ok
// Go does not allow nil as a key

Removing Elements

// Java
map.remove("key");      // returns the removed value (or null)

// Go
delete(m, "key")        // does not return a value
value, ok := m["key"]   // need to check separately

Iteration Guarantees

// Java
// No order guarantees (may change)
for (String key : map.keySet()) {
    // order is undefined
}

// Go
// Intentionally randomized (since Go 1.0)
for k, v := range m {
    // order is random to prevent developers from relying on it
}

Thread-safety

// Java
HashMap<String, String> map = new HashMap<>();  // not thread-safe
ConcurrentHashMap<String, String> cmap = new ConcurrentHashMap<>();  // thread-safe

// Go
m := make(map[string]string)  // not thread-safe (data race)
var mu sync.RWMutex           // requires a mutex
// when working with a map, you must mutex lock() and unlock()

Methods vs. Built-in Functions

// Java
map.put("key", "value");
map.get("key");
map.containsKey("key");
map.size();

// Go
m["key"] = "value"    // built-in syntax
value := m["key"]     // if key is missing - zero value
_, ok := m["key"]     // check for existence
len(m)                // built-in function

Internal Implementation

Java:

HashMap - an array of buckets with linked lists (chaining)
Initial number of buckets: 16
Upon collision: > 8 elements in a single bucket + total size > 64 → the list is converted into a red-black tree (Treeify)
load factor 0.75
You can specify the initial capacity (nearest power of two)

new HashMap<>();        // 16 buckets
new HashMap<>(100);     // 128 buckets (nearest power of 2)

When Rehashing Occurs in Java HashMap

HashMap<String, String> map = new HashMap<>(16); // capacity=16, threshold=12 (16*0.75)

// Adding 12 elements — OK
for(int i=0; i<12; i++) map.put("key"+i, "value");
// Size = 12, threshold = 12

map.put("key12", "value");  // 13th element
// Rehash: capacity = 32, threshold = 24 (32*0.75)
// All 13 elements are redistributed

Rehash conditions:

size >= threshold (threshold = capacity * load_factor)
Only after put() (insertion)

Go:

map - a hash table with "buckets" containing 8 elements each
Each bucket: 8 slots (a bucket with 8 elements)
When a bucket is full: an overflow bucket is created (not a new bucket, but an additional linked chain)
When load factor > ~6.5: growing occurs (doubling the number of buckets) with incremental evacuation (incremental rehashing)

make(map[string]int)        // small initial size
make(map[string]int, 100)   // ~14-16 buckets (100/8 * ~1.2)

There is no Java-style rehash in Go. Instead:

Incremental evacuation (incremental rehashing)
During growth, new buckets are created, but elements are migrated gradually (1-2 elements at a time on each map access)
There is no long blocking pause for rebuilding the entire table

Size at creation

// Java
new HashMap<>();        // default capacity 16
new HashMap<>(100);     // capacity = nearest power of two (128)

// Rule: returns the nearest power of two ≥ cap
/*
    cap = 100  → 128  (2^7)
    cap = 120  → 128  (2^7)
    cap = 128  → 128  (power of two)
    cap = 129  → 256  (2^8)
    cap = 200  → 256
*/

// Go
make(map[string]int)         // hint = 0 (normal growth)
make(map[string]int, 100)    // allocation hint (not the exact capacity)

Default Values

// Java
map.get("missing")  // returns null

// Go
m["missing"]  // returns zero value (0 for int, "" for string)
             // to distinguish from an actual "": value, ok := m["key"]

Storing Structs

// Java - can be modified via get, as references are stored
HashMap<String, User> map = new HashMap<>();
map.put("key", new User("Bob"));
map.get("key").setName("John");  // works

// Go
type User struct { Name string }

m := make(map[string]User)

u := m["key"]
u.Name = "John"  // won't compile (cannot modify a value in a map directly)

user := m["key"]
user.Name = "John"  // modify via a temporary variable
m["key"] = user     // write it back

DEV Community: Silver_dev

Spring Boot Under the Hood. Part 9: Actuator, DevTools and the Rest of the Toolbox

9.1. Actuator — Production-Ready Monitoring

9.1.1. Adding it

9.1.2. Built-in Endpoints

9.1.3. Your Own @Endpoint

9.1.4. HealthIndicators

9.1.5. Micrometer

9.1.6. Boot 4: Actuator Changes

9.2. Logging

9.2.1. The Defaults

9.2.2. Configuration

9.2.3. Levels via Properties

9.2.4. Structured Logging (Boot 3.4+)

9.2.5. Boot 4: Changes

9.3. DevTools — Speeding Up Development

9.3.1. Automatic Restart

9.3.2. LiveReload

9.3.3. include/exclude Configuration

9.3.4. Global Settings

9.4. Testing

9.4.1. @SpringBootTest — the Full Context

9.4.2. Slice Tests — Narrow Contexts

9.4.3. @MockitoBean — Replacing @MockBean in Boot 4

9.4.4. ApplicationContextRunner — Testing Auto-configurations

9.5. Build and Packaging

9.5.1. spring-boot-maven-plugin

9.5.2. Layered JAR

9.5.3. JarLauncher

9.5.4. Buildpacks

9.5.5. Boot 4: Changes

9.6. AOT and GraalVM Native Image (an Overview)

9.6.1. What Is AOT

9.6.2. RuntimeHintsRegistrar

9.6.3. @RegisterReflectionForBinding — a Shortcut

9.6.4. Building a Native Image

9.6.5. Boot 4: AOT by Default

9.7. Summary Table: Boot 3 vs Boot 4

9.8. Key Takeaways

Spring Boot Under the Hood. Part 8: Graceful Exit — How Spring Boot Starts and Stops

8.1. ApplicationRunner and CommandLineRunner — the Entry Point into the "Ready" Application

8.2. The Order in Which Runners Are Invoked

8.3. The Rule: Runners Instead of @PostConstruct

8.4. Graceful Shutdown

8.5. WebServerGracefulShutdownLifecycle — the Implementation

8.6. SmartLifecycle and LifecycleProcessor — the Start/Stop Order

8.7. The JVM Shutdown Hook — How the JVM Knows It's Time to Stop

8.8. Closing the Context Manually

8.9. Spring Boot 3 vs Spring Boot 4 — the Differences

8.10. Key Takeaways

Spring Boot Under the Hood. Part 7: From Embedded Tomcat to Your @RestController

7.1. Servlet vs Reactive — Two Parallel Worlds

7.2. Web Server Auto-configuration — ServletWebServerFactoryAutoConfiguration

7.2.1. EmbeddedTomcat — Picking the Server

7.3. ServletWebServerApplicationContext.onRefresh() — Creating the Server

7.3.1. getSelfInitializer() — the Bridge to ServletContextInitializer

7.3.2. ServletContextInitializerBeans — Collecting All the Initializers

7.4. WebServerStartStopLifecycle — Starting Tomcat

7.5. DispatcherServletAutoConfiguration — Creating the DispatcherServlet

7.6. WebMvcAutoConfiguration — Wiring Up Spring MVC

7.7. ErrorMvcAutoConfiguration — Error Handling

7.7.1. BasicErrorController — the /error Handler

7.7.2. DefaultErrorAttributes — the Error Model

7.7.3. ErrorPageCustomizer — Registering the Error Page

7.8. Server Customization — ServerProperties

7.8.1. ServletWebServerFactoryCustomizer — Applying the Properties

7.8.2. Your Own WebServerFactoryCustomizer

7.9. The Reactive Stack — WebFlux and Netty

7.9.1. ReactiveWebServerFactoryAutoConfiguration

7.9.2. NettyReactiveWebServerFactory

7.9.3. Key Differences from Servlet

7.10. Spring Boot 3 vs Spring Boot 4 — Key Differences

7.10.1. Modularization

7.10.2. Undertow Is Gone

7.10.3. Class Relocations

7.10.4. What Hasn't Changed

7.11. Diagram: Creating the Web Server (Servlet)

7.12. Key Takeaways

Spring Boot Under the Hood. Part 6: Bean Lifecycle — Born, Post-Processed, Destroyed

6.1. BeanDefinition — the Bean's Blueprint

9.1.3. Your Own `@Endpoint`

Step 1: `createBean()` — the entry point

Step 2: `resolveBeforeInstantiation()` — the early proxy

Step 4: `createBeanInstance()` — choosing the constructor

Step 5: `populateBean()` — injecting dependencies

Step 6: `initializeBean()` — initialization