Runners

A runner is a bean whose run method is called once the application has started: database migrations, a cache warm-up, the job of a command-line tool. Runners run one after another, sorted by @Order, as in Spring Boot.

Why

Start-up work needs every bean to exist, and it often has to happen in a given order: the schema must be migrated before the warm-up reads it. A runner is called after the context is ready, and the next one starts only when the previous one (its Future included) is done. A failing runner stops the application with a report, instead of leaving it half started.

Example

// The schema must be up to date before anything else touches the database.
@Component()
@Order(1)
class Migrations implements ApplicationRunner {
  Migrations(this.db);

  final Database db;

  @override
  Future<void> run(ApplicationArguments args) => db.migrate(); // awaited
}

// Starts only after Migrations has finished.
@Component()
@Order(2)
class Warmup implements ApplicationRunner {
  Warmup(this.catalog);

  final Catalog catalog;

  @override
  Future<void> run(ApplicationArguments args) => catalog.loadBestsellers();
}

// A command-line job: dart run bin/main.dart --dry-run books.csv
@Component()
class Importer implements ApplicationRunner {
  Importer(this.books);

  final BookStore books;

  @override
  Future<void> run(ApplicationArguments args) async {
    final dryRun = args.containsOption('dry-run');
    for (final file in args.nonOptionArgs) {
      await books.importCsv(file, save: !dryRun);
    }
  }
}

The two kinds

Interface run receives Use
ApplicationRunner ApplicationArguments: options and plain arguments, parsed Most runners
CommandLineRunner List<String>: the arguments exactly as main got them Code that parses arguments itself

Both may return void or a Future. A bean that implements both is called as both.

Order and timing

When a runner fails

The failure is reported as Application run failed with the error, ApplicationFailedEvent is published and the context is closed. With runApplication, an asynchronous failure is rethrown outside any try, which ends the program with a non-zero code. With runApplicationAsync, the returned Future fails.

An exit code for the failure comes from ExitCodeExceptionMapper beans, or from the exception itself when it implements ExitCodeGenerator; see Shutdown and exit codes.

ApplicationArguments

SpringApplication parses the arguments once and registers the result as a bean, so any bean can inject it.

Member Meaning
sourceArgs The arguments as main received them
optionNames The names of the options given (dry-run for --dry-run)
containsOption(name) Whether the option was given, with or without a value; the name without dashes
getOptionValues(name) The values in order (['a', 'b'] for --tag=a --tag=b); [] for a bare --name; null when not given
nonOptionArgs The plain arguments: those not starting with --, and everything after a lone --

Options are --name=value or a bare --name; only the first = separates. -v is a plain argument. Options are also properties, so --server.port=8081 sets server.port; most settings are read with @Value or @ConfigurationProperties rather than from here.

Runners and hot reload

When a Flutter hot reload restarts the context (beans or configuration changed), the runners run again by default, like after a Spring Boot DevTools restart. reloadApplication(context, runners: false) restarts the beans without repeating migrations, analytics events or network calls. See Hot reload.

In Spring (Java)

@Component
@Order(1)
class Migrations implements ApplicationRunner {
  public void run(ApplicationArguments args) { db.migrate(); }
}

The same interfaces and order. A runner returning a Future is awaited before the next one, which Java has no need for.

See also