Course topics

By WebNest Studio Engineering Team

Spring Boot Tutorial

Application Startup: Runners and Lifecycle Events

Many applications need to do something when they start — load reference data, warm a cache, validate configuration, print a summary, or start a background consumer — and something when they stop, like flushing buffers or finishing in-flight work. Spring Boot offers several hooks for this, each running at a different moment of the lifecycle.

This lesson walks through the startup sequence of SpringApplication, CommandLineRunner and ApplicationRunner, the lifecycle events you can listen to, SmartLifecycle for components that start and stop, graceful shutdown, and customising SpringApplication itself.

The Startup Sequence

When SpringApplication.run() executes, events are published in a fixed order: ApplicationStartingEvent → ApplicationEnvironmentPreparedEvent (configuration loaded) → ApplicationContextInitializedEvent → ApplicationPreparedEvent (bean definitions loaded) → context refresh (beans created, @PostConstruct runs, web server starts) → ApplicationStartedEvent → runners execute → ApplicationReadyEvent (the application is ready to serve). If anything fails, ApplicationFailedEvent is published instead.

CommandLineRunner and ApplicationRunner

Beans implementing these interfaces run once, after the context has started and before the application is marked ready. CommandLineRunner.run(String... args) gets raw arguments; ApplicationRunner.run(ApplicationArguments args) gets parsed options (--mode=import) and non-option arguments. Order several runners with @Order. Exceptions thrown from a runner stop the application — useful for fail-fast checks. Runners are ideal for CLI-style Spring Boot tools and one-off data setup.

Listening to Events

Use @EventListener(ApplicationReadyEvent.class) for work that should only happen once the app is fully ready — for example registering with an external system or logging a startup summary. Early events (starting, environment prepared) fire before the context exists, so their listeners must be registered via SpringApplication.addListeners() or META-INF/spring.factories, not as beans.

SmartLifecycle for Start/Stop Components

Components that own a background thread or connection — a message poller, a scheduler, a socket server — should implement SmartLifecycle. Spring calls start() after all singletons are created and stop() during shutdown, in an order controlled by getPhase(). Combined with graceful shutdown, this lets in-flight work complete before the JVM exits.

Graceful Shutdown

Spring Boot enables graceful shutdown by default for embedded web servers: on SIGTERM, the server stops accepting new requests and waits for active ones to finish, up to spring.lifecycle.timeout-per-shutdown-phase (30s by default). Then lifecycle beans stop, @PreDestroy methods run and the context closes. This is essential for zero-downtime deployments on Kubernetes.

Examples

CommandLineRunner and ApplicationRunner with ordering

Java
@Component
@Order(1)
public class SeedDataRunner implements CommandLineRunner {

    private final CourseRepository courses;

    public SeedDataRunner(CourseRepository courses) {
        this.courses = courses;
    }

    @Override
    public void run(String... args) {
        if (courses.count() == 0) {
            courses.saveAll(List.of(new Course("java-core", "Java - Core"),
                                    new Course("spring-boot", "Spring Boot")));
            System.out.println("Seeded 2 courses");
        }
    }
}

@Component
@Order(2)
public class ImportRunner implements ApplicationRunner {

    @Override
    public void run(ApplicationArguments args) {
        if (args.containsOption("import")) {
            String file = args.getOptionValues("import").get(0);
            System.out.println("Importing students from " + file);
        }
        System.out.println("Non-option args: " + args.getNonOptionArgs());
    }
}
Output
java -jar app.jar --import=students.csv dry-run

Seeded 2 courses
Importing students from students.csv
Non-option args: [dry-run]
Started WebnestAppApplication in 2.1 seconds

Reacting to ApplicationReadyEvent and failing fast on bad configuration

Java
@Component
public class StartupReporter {

    private static final Logger log = LoggerFactory.getLogger(StartupReporter.class);
    private final Environment env;

    public StartupReporter(Environment env) {
        this.env = env;
    }

    @EventListener(ApplicationReadyEvent.class)
    public void ready(ApplicationReadyEvent event) {
        log.info("Ready on port {} with profiles {} in {} ms",
            env.getProperty("local.server.port"),
            Arrays.toString(env.getActiveProfiles()),
            event.getTimeTaken().toMillis());
    }
}

@Component
class RequiredConfigCheck implements ApplicationRunner {

    @Value("${payments.api-key:}")
    private String apiKey;

    @Override
    public void run(ApplicationArguments args) {
        if (apiKey.isBlank()) {
            throw new IllegalStateException("payments.api-key must be set");   // stops the app
        }
    }
}
Output
INFO  StartupReporter : Ready on port 8080 with profiles [dev] in 2143 ms

(without the key)
ERROR SpringApplication : Application run failed
java.lang.IllegalStateException: payments.api-key must be set

A SmartLifecycle background worker with graceful shutdown

Java
@Component
public class OutboxPublisher implements SmartLifecycle {

    private static final Logger log = LoggerFactory.getLogger(OutboxPublisher.class);
    private final ScheduledExecutorService executor = Executors.newSingleThreadScheduledExecutor();
    private volatile boolean running;

    @Override
    public void start() {
        running = true;
        executor.scheduleWithFixedDelay(this::publishPending, 0, 1, TimeUnit.SECONDS);
        log.info("Outbox publisher started");
    }

    @Override
    public void stop() {
        running = false;
        executor.shutdown();
        try {
            executor.awaitTermination(10, TimeUnit.SECONDS);   // finish the current batch
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        log.info("Outbox publisher stopped");
    }

    @Override
    public boolean isRunning() {
        return running;
    }

    private void publishPending() { /* read outbox table, send events */ }
}

# application.yml
server:
  shutdown: graceful          # default in Spring Boot, shown for clarity
spring:
  lifecycle:
    timeout-per-shutdown-phase: 20s
Output
INFO  Outbox publisher started
(Ctrl+C / SIGTERM)
INFO  GracefulShutdown : Commencing graceful shutdown. Waiting for active requests to complete
INFO  GracefulShutdown : Graceful shutdown complete
INFO  Outbox publisher stopped

Customising SpringApplication

Java
public static void main(String[] args) {
    SpringApplication app = new SpringApplication(WebnestAppApplication.class);
    app.setBannerMode(Banner.Mode.OFF);
    app.setDefaultProperties(Map.of("server.port", "8081"));
    app.addListeners((ApplicationListener<ApplicationEnvironmentPreparedEvent>) e ->
        System.out.println("Environment ready, profiles = "
            + Arrays.toString(e.getEnvironment().getActiveProfiles())));
    app.run(args);
}
Output
Environment ready, profiles = []
Tomcat started on port 8081 (http)

Common Mistakes

  • Doing slow work (large imports) in @PostConstruct, delaying startup and blocking health checks; use a runner or ApplicationReadyEvent and consider async execution.
  • Swallowing exceptions in startup checks, so a misconfigured application starts "successfully" and fails later.
  • Registering early lifecycle event listeners as @Component beans; they fire before the context exists and never reach the bean.
  • Starting threads in constructors without stopping them, preventing clean shutdown.
  • Setting a Kubernetes termination grace period shorter than the Spring shutdown timeout, so pods are killed mid-request.

Exercise

Using the lesson's CommandLineRunner and ApplicationRunner with ordering example, create a small implementation or design sketch that demonstrates SpringApplication publishes lifecycle events from ApplicationStartingEvent to ApplicationReadyEvent.. Add a test case or scenario that would catch Doing slow work (large imports) in @PostConstruct, delaying startup and blocking health checks; use a runner or ApplicationReadyEvent and consider async execution., and describe the expected result.

Show hints
  • Start with The Startup Sequence and compare your approach with CommandLineRunner and ApplicationRunner with ordering. Identify the decision or behavior the lesson recommends.
  • Walk through your scenario step by step. Confirm that it follows SpringApplication publishes lifecycle events from ApplicationStartingEvent to ApplicationReadyEvent. and that it would catch the failure described by Doing slow work (large imports) in @PostConstruct, delaying startup and blocking health checks; use a runner or ApplicationReadyEvent and consider async execution..

Quick quiz

1. Which choice is a mistake to avoid in Application Startup: Runners and Lifecycle Events?

  • A. Swallowing exceptions in startup checks, so a misconfigured application starts "successfully" and fails later.
  • B. SpringApplication publishes lifecycle events from ApplicationStartingEvent to ApplicationReadyEvent.
  • C. Doing slow work (large imports) in @PostConstruct, delaying startup and blocking health checks; use a runner or ApplicationReadyEvent and consider async execution.
Show answer

C. Avoid this approach: Doing slow work (large imports) in @PostConstruct, delaying startup and blocking health checks; use a runner or ApplicationReadyEvent and consider async execution. The lesson recommends: SpringApplication publishes lifecycle events from ApplicationStartingEvent to ApplicationReadyEvent.

Interview questions

A teammate is about to make this mistake: Doing slow work (large imports) in @PostConstruct, delaying startup and blocking health checks; use a runner or ApplicationReadyEvent and consider async execution. How would you diagnose and correct it using the lesson's guidance?

Show answer

SpringApplication publishes lifecycle events from ApplicationStartingEvent to ApplicationReadyEvent. Apply this in The Startup Sequence; the example CommandLineRunner and ApplicationRunner with ordering shows one way to do it. Avoid Doing slow work (large imports) in @PostConstruct, delaying startup and blocking health checks; use a runner or ApplicationReadyEvent and consider async execution. and explain how your implementation or design prevents that failure.

Key Points to Remember

  • SpringApplication publishes lifecycle events from ApplicationStartingEvent to ApplicationReadyEvent.
  • CommandLineRunner and ApplicationRunner run once after startup; order them with @Order.
  • Use @EventListener(ApplicationReadyEvent.class) for work that needs a fully ready app.
  • SmartLifecycle manages components with start/stop behaviour and phases.
  • Graceful shutdown lets active requests finish; tune spring.lifecycle.timeout-per-shutdown-phase.

Practice in the playground

Write and run your own code for this topic, or start from the exercise or an example. Runs plain Java 17. Frameworks such as Spring, and databases, are not available here. Your code for each topic is kept in this browser.

Run the examples

Change an input, predict the result, then compare it with the output. Explain why the result changes.

These examples need a JDK project with their libraries on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.

WebNest Studio

Written by

WebNest Studio Engineering Team

Practical lessons from developers working with Java, Python, React, databases and production systems.

Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering