
# 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](../spring-core-dart/observations/index.md).

## 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

```yaml
# 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
```

```dart
// 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);
}
```

```properties
# 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:

```dart
// 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](../spring-core-dart/json/index.md).

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](json-schema.md).

## Validation

- `defaultValidator`, a `BeanValidator` that checks constraint annotations such as `@NotBlank()`. Inject `Validator` to validate objects by hand. Your own `BeanValidator` bean replaces it; a bean that only implements the plain `Validator` interface does not.
- `methodValidationPostProcessor` checks the parameters and return values of the methods of `@Validated()` beans. It uses the single `BeanValidator` bean, or a new one when there is none or several. `@ConfigurationProperties` classes 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](../spring-core-dart/validation/index.md).

## 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](../spring-core-dart/messages/index.md).

## 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](shutdown.md).

## Availability

`applicationAvailability` keeps the last `LivenessState` and `ReadinessState`. See [Events](events.md#availability).

## 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.

```dart
@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](../spring-core-dart/isolates/index.md), [The task executor](../spring-core-dart/isolates/task-executor.md), [The load of the isolates](../spring-core-dart/isolates/load.md) and [Asking the first isolate](../spring-core-dart/isolates/primary-isolate.md). `@ConditionalOnPrimaryIsolate` is on [Conditions](conditions.md#conditionalonprimaryisolate).

## 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.

## See also

- [Auto-configuration and starters](auto-configuration.md)
- [Isolates](../spring-core-dart/isolates/index.md)
- [All properties](properties.md)
- [JSON](../spring-core-dart/json/index.md)
- [JSON Schema beans](json-schema.md)
- [Validation](../spring-core-dart/validation/index.md)
- [Messages](../spring-core-dart/messages/index.md)
