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
- Runners are sorted by
@Order(orOrdered), lowest first; runners without an order come last. - Each runner finishes, its
Futureincluded, before the next starts. - They run after
ApplicationStartedEventand after anyAsyncStartupbean (the web server listening), and beforeApplicationReadyEvent. - If the context is closed meanwhile, the remaining runners are skipped.
runApplicationreturns once the synchronous part is done; asynchronous runners then go on.await runApplicationAsync(args)completes after the last runner.
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.