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

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:

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:

1. Both types are collected into a single list.
2. Sorting is done via AnnotationAwareOrderComparator — by @Order / Ordered.
3. @Order only affects the order in which run() is invoked — not the order in which the beans are created.
4. 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:

1. The application receives a SIGTERM signal (e.g., from Kubernetes).
2. The JVM shutdown hook initiates context.close().
3. The first phase — stop accepting new requests.
4. Existing requests get a grace period to finish.
5. 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:

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:

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

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

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