
# The app lifecycle

Each change of Flutter's `AppLifecycleState` is published as an `AppLifecycleStateEvent`, so any bean can react without a widget in between. When the app goes to the background, the application context is paused: `@Scheduled` tasks, WebSocket connections and the other pauseable lifecycle beans stop. When it comes back, they start again.

## Why

A phone app in the background should not poll servers, keep sockets open or run timers: it costs battery and data, and the system may kill it for that. With Spring's lifecycle in the context, the beans that run work in the background (schedulers, socket clients) stop and start by themselves, and your own beans react to the same events.

## Example

```dart
// An unsent draft is saved when the user leaves the app.
@Component()
class DraftKeeper {
  DraftKeeper(this.drafts);

  final DraftStore drafts;

  @EventListener()
  void onLifecycle(AppLifecycleStateEvent event) {
    if (event.state == AppLifecycleState.paused) drafts.save();
  }
}
```

## The events

| Event | When |
|---|---|
| `AppLifecycleStateEvent` | At every change of the state: `resumed`, `inactive`, `hidden`, `paused` or `detached` (`event.state`) |
| `ContextPausedEvent` | After the context paused, when the app went to the background (`hidden` or `paused`) |
| `ContextRestartedEvent` | After the context started again, when the app is `resumed` |
| `ContextClosedEvent` | When `SpringApplicationWidget` is removed, or a hot reload restarts the context |

## The pause in the background

When the app goes to the background (`hidden` or `paused`), the context is paused: `@Scheduled` tasks, WebSocket connections and the other pauseable `SmartLifecycle` beans stop, then a `ContextPausedEvent` is published. Back in the foreground (`resumed`), they start again and a `ContextRestartedEvent` follows. It is the context's `pause()` and `restart()` of Spring Framework 7.

To keep them running in the background:

```yaml
spring:
  flutter:
    lifecycle:
      pause-in-background: false
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.lifecycle.pause-in-background` | bool | `true` | Pauses the context while the app is in the background, and starts it again in the foreground |

## Scheduled work and the background

- `@Scheduled` tasks are scheduled afresh when the app comes back, so the runs missed in the background are not made up.
- Tasks a bean starts itself with the `TaskScheduler` (`scheduleAtFixedRate`, `scheduleWithFixedDelay`, ...) are not paused. They keep running while the system lets the app run, and when it suspended the app, they catch up on its return as Spring's scheduler does. A fixed-rate task then starts every run missed meanwhile at once (a 1-second rate after a minute away: about 60 runs back to back); a fixed-delay one runs once and goes on.
- So give polls and UI ticks a fixed delay, or cancel them when their screen goes away, or on `ContextPausedEvent`. The same holds for `@Scheduled(fixedRate: ...)` with `pause-in-background=false`, and for a browser tab whose timers are throttled while hidden.

## A lifecycle bean of your own

A bean that holds a connection mixes in `SmartLifecycle`. It is pauseable by default (`isPauseable` is `true`); override it with `false` for a bean that must keep running in the background:

```dart
// A live feed of prices that stops in the background.
@Component()
class PriceFeed with SmartLifecycle {
  PriceFeed(this.socket);

  final PriceSocket socket;
  var _running = false;

  @override
  void start() {
    socket.connect();
    _running = true;
  }

  @override
  void stop() {
    socket.close();
    _running = false;
  }

  @override
  bool get isRunning => _running; // stopped by pause(), started by restart()
}
```

## The end of the context

The context is closed when `SpringApplicationWidget` is removed from the tree: `@PreDestroy` methods run and lifecycle beans stop. A hot reload that changed beans closes it too, then starts a new one (see [Hot reload](hot-reload.md)).

## In Spring (Java)

A server has no foreground and background, so Spring has no `AppLifecycleStateEvent`. `pause()` and `restart()` and their events are Spring Framework 7's.

## See also

- [Hot reload](hot-reload.md)
- [Events in spring_core_dart](../spring-core-dart/events/index.md)
- [Context events](../spring-core-dart/events/context-events.md)
