Built-in beans
spring_boot_dart is a starter too. Its auto-configuration module, springBootAutoConfiguration, adds these auto-configurations to every application. Each one backs off when the application declares its own bean, and each can be excluded by name.
| Auto-configuration | Bean | Backs off when the application has |
|---|---|---|
JacksonAutoConfiguration |
jacksonJsonMapper, an ObjectMapper |
an ObjectMapper bean |
ValidationAutoConfiguration |
defaultValidator (a BeanValidator) and methodValidationPostProcessor |
a BeanValidator bean; a MethodValidationPostProcessor bean |
MessageSourceAutoConfiguration |
messageSource |
a bean named messageSource in this context, or no bundle file |
LifecycleAutoConfiguration |
lifecycleProcessor with the shutdown timeout |
a bean named lifecycleProcessor in this context |
ApplicationAvailabilityAutoConfiguration |
applicationAvailability |
an ApplicationAvailability bean |
JsonSchemaAutoConfiguration |
jsonSchemaRegistry |
a JsonSchemaRegistry bean |
ObservationAutoConfiguration |
observationRegistry, with every ObservationHandler bean |
an ObservationRegistry bean |
IsolateAutoConfiguration |
isolateInfo, isolateLoadSampler, isolateTaskExecutor, isolateLoads, isolateReports, primaryIsolate |
a bean of the same type, each on its own |
springBootObservedAnnotationsAutoConfiguration, a module of its own, adds the observedAdvisor that puts @Observed into effect, only with spring.observations.annotations.enabled: true: without it the module is not in the build and no bean gets a proxy for @Observed. See Observations and the start.
Why
Nearly every application needs JSON, validation, translated messages and a clean shutdown. Spring Boot configures them from properties; so does spring_boot_dart, with the same names where they make sense. Declaring your own bean replaces the default completely, so nothing is hidden.
Example
# lib/resources/application.yml
spring:
json:
property-naming-strategy: SNAKE_CASE
default-property-inclusion: non_null
serialization:
indent-output: true
messages:
basename: messages,i18n/errors
fallback-to-system-locale: false
lifecycle:
timeout-per-shutdown-phase: 20s
// The mapper, the validator and the message source are ready to inject.
@Service()
class Catalog {
Catalog(this.mapper, this.validator, this.messages);
final ObjectMapper mapper;
final Validator validator;
final MessageSource messages;
String export(List<Book> books) => mapper.writeValueAsString(books);
List<Book> import(String json) => mapper.readList<Book>(json);
}
# Switch one off
spring.autoconfigure.exclude=JacksonAutoConfiguration
JSON: the ObjectMapper
The jacksonJsonMapper bean (Spring Boot 4's name) reads and writes JSON. The web starter uses the same bean for request and response bodies. It knows every @Introspected class of the application, and adds every JsonSerializer, JsonDeserializer and JsonModule bean (Spring Boot's @JsonComponent).
| Key | Default | Meaning |
|---|---|---|
spring.json.property-naming-strategy |
LOWER_CAMEL_CASE |
How field names become JSON names: SNAKE_CASE, UPPER_SNAKE_CASE, UPPER_CAMEL_CASE, LOWER_CAMEL_CASE, LOWER_CASE, KEBAB_CASE, LOWER_DOT_CASE |
spring.json.default-property-inclusion |
always |
Which properties are written: always, non_null, non_absent, non_empty, non_default |
spring.json.time-zone |
none: each date in its own zone | UTC, Z or a fixed offset (+02:00). A named zone (Europe/Berlin) stops the start: Dart has no time zone database |
spring.json.serialization.indent-output |
false |
Pretty-printed JSON |
spring.json.serialization.write-dates-as-timestamps |
false |
DateTime as epoch seconds with a fraction (Jackson 3) |
spring.json.serialization.write-durations-as-timestamps |
false |
Duration as seconds |
spring.json.serialization.write-date-timestamps-as-nanoseconds |
true |
false: timestamps in milliseconds |
spring.json.deserialization.read-date-timestamps-as-nanoseconds |
true |
Integer timestamps are seconds; false: milliseconds |
spring.json.deserialization.fail-on-unknown-properties |
false |
A JSON property the class does not have fails the read |
spring.json.deserialization.accept-float-as-int |
true |
1.5 into an int truncates; false rejects it |
spring.json.deserialization.fail-on-null-for-primitives |
true |
null (or a missing constructor value) for a non-nullable int, double, num or bool fails the read; false reads 0 or false |
spring.json.mapper.sort-properties-alphabetically |
true |
Properties sorted by JSON name, constructor parameters first (Jackson 3's order); false: declaration order |
spring.json.mapper.default-view-inclusion |
false |
Properties without @JsonView are written with a view |
spring.json.datatype.datetime.write-dates-as-timestamps |
the serialization. value |
Spring Boot 4's name; wins over the serialization. key |
spring.json.datatype.datetime.write-durations-as-timestamps |
the serialization. value |
Wins over the serialization. key |
spring.json.datatype.datetime.write-date-timestamps-as-nanoseconds |
the serialization. value |
Wins over the serialization. key |
spring.json.datatype.datetime.read-date-timestamps-as-nanoseconds |
the deserialization. value |
Wins over the deserialization. key |
The booleans are bound strictly: a value that is not a boolean stops the start. Any other spring.json.* key (date-format, locale, Jackson's feature flags) is logged as a warning naming the supported keys, and ignored. spring.jackson.* stops the start and names the new key.
To change one thing without losing the properties, declare a JsonMapperBuilderCustomizer bean (Spring Boot 4's). Customizers run after the properties are applied, in @Order, so they win:
// Pretty JSON, whatever the properties say.
@Bean()
JsonMapperBuilderCustomizer indented() => JsonMapperBuilderCustomizer.of(
(builder) => builder.enable(SerializationFeature.indentOutput),
);
objectMapperFromProperties(environment) builds the same mapper by hand, for a tool without beans, a test or a second mapper. See JSON.
The JSON Schemas of the application (spring.json.schemas, @JsonSchemaSource) are beans of their own, and the mapper checks JSON against them: see JSON Schema beans.
Validation
defaultValidator, aBeanValidatorthat checks constraint annotations such as@NotBlank(). InjectValidatorto validate objects by hand. Your ownBeanValidatorbean replaces it; a bean that only implements the plainValidatorinterface does not.methodValidationPostProcessorchecks the parameters and return values of the methods of@Validated()beans. It uses the singleBeanValidatorbean, or a new one when there is none or several.@ConfigurationPropertiesclasses are left out: there,@Validated()means validation after binding.
The default validator has no message source, so a {key} in a constraint message stays as written instead of being looked up. See Validation.
Messages
messageSource reads translated texts from lib/resources/messages.properties and messages_<locale>.properties. It is registered only when a bundle file of a configured base name exists, and when the context (not counting a parent) has no bean named messageSource.
| Key | Type | Default | Meaning |
|---|---|---|---|
spring.messages.basename |
list | messages |
The base names. i18n/errors (or i18n.errors) reads lib/resources/i18n/errors_{locale}.properties |
spring.messages.encoding |
charset | UTF-8 | The files' encoding; an unknown one stops the start |
spring.messages.cache-duration |
Duration; a plain number is seconds |
kept forever | How long a loaded file is kept before it is read again |
spring.messages.fallback-to-system-locale |
bool | true |
Tries the system's locale before the file without a locale |
spring.messages.use-code-as-default-message |
bool | false |
A missing key returns the key itself instead of failing |
spring.messages.always-use-message-format |
bool | false |
Formats messages without arguments too, so '' becomes ' |
spring.messages.default-locale |
locale | none | A locale tried before the system's (not in Spring Boot; apps often have no meaningful system locale) |
spring.messages.common-messages |
list of locations | none | Texts shared by every locale; a later file wins |
See Messages.
The lifecycle processor
When the context closes, the lifecycleProcessor stops the lifecycle beans phase by phase and waits at most spring.lifecycle.timeout-per-shutdown-phase (30 s by default, as in Spring Boot) for each phase, for example for the web server's graceful shutdown. Without this bean the context's own processor waits 10 s (Spring Framework's default), whatever the property says. See Shutdown.
Availability
applicationAvailability keeps the last LivenessState and ReadinessState. See Events.
Isolates
IsolateAutoConfiguration declares these beans, each of the first six left out when the application declares a bean of its type:
| Bean | Type | What it is |
|---|---|---|
isolateInfo |
IsolateInfo |
The isolate the context runs in: its name, its number in a pool, whether it is the application's first |
isolateLoadSampler |
IsolateLoadSampler |
How busy that isolate is. It measures only while someone reads it, and stops with the context |
isolateTaskExecutor |
IsolateTaskExecutor |
A pool of isolates for work that would block, configured by spring.task.execution.isolates.*. It starts no isolate before its first task and is shut down with the context |
isolateLoads |
IsolateLoads |
The load of every isolate known, from each IsolateLoadSource bean: the two above, the web server's, and your own |
isolateReports |
IsolateReports |
What each isolate of a pool tells the first one, from each IsolateReporter bean |
primaryIsolate |
PrimaryIsolate |
Asks the application's first isolate, where each PrimaryIsolateHandler bean answers; the same call in every isolate |
isolateLoadsHandler |
IsolateLoadsHandler |
One such handler (isolates.loads): answers every isolate's load, so a request that reaches any isolate can show them all |
None of them costs anything until it is used: no timer runs and no isolate is started in an application that never reads a load and never submits a task.
@Service()
class Thumbnails {
Thumbnails(this.isolates, this.isolate);
final IsolateTaskExecutor isolates;
final IsolateInfo isolate;
// Resizing would block the isolate that answers requests or draws.
Future<Uint8List> resize(Uint8List image) =>
isolates.submitWith(_resize, image);
static Uint8List _resize(Uint8List image) => /* ... */ image;
}
In an isolate of the web server's pool the task executor's isolates carry that isolate's name (isolate-2-task-1), so every task isolate of the application has a name of its own.
In a browser isolateTaskExecutor runs a task in the calling isolate, since no isolate can be started there; the code that uses it is the same.
See Isolates, The task executor, The load of the isolates and Asking the first isolate. @ConditionalOnPrimaryIsolate is on Conditions.
In Spring (Java)
Spring Boot's TaskExecutionAutoConfiguration is the counterpart of the task executor; the other isolate beans have none. The same auto-configuration names and properties, except that spring.jackson.* is spring.json.* and only the keys above are read. JsonMapperBuilderCustomizer gets the core JsonMapperBuilder (naming, inclusion, time zone, features, serializers, modules), not Jackson's full builder.