
# Caches that outlive a restart

`spring.cache.type: disk` keeps every entry on disk, so a result survives a restart of the app: an API answer a phone asked for yesterday is there at the next start, without the network.

## Why

The in-memory caches are empty after every start. On a phone that is every time the user opens the app, and on the web every time the page loads: the same answers are asked for again. A store on disk keeps them; it answers later than memory, so its caches are for methods that return a `Future`.

## Example

```yaml
spring:
  cache:
    type: disk                # simple: memory; disk: kept across restarts
    disk:
      time-to-live: 1h        # by the wall clock: it outlives a restart
      max-size: 50MB          # per cache; the oldest written go first
      version: 2.1.0          # an entry of another version is not read
      caches:
        profiles: { time-to-live: 10m }
```

```dart
@Component()
class Profiles {
  Profiles(this.api);
  final PassportApi api;

  @Cacheable('profiles')
  Future<Profile> find(String steamId) => api.profile(steamId);
}
```

## How it works

- **Where.** In the application's `CacheStore`: a Flutter app's `cache` place (which the system may clear; IndexedDB in a browser), given by the Flutter starter; elsewhere a folder, `spring.cache.disk.directory` (`.spring/cache` by default). One file an entry: `spring/caches/<cache>/<hash of the key>.json`, with the key it was written under, its expiry, its version and the value.
- **Data, not files.** These caches hold the results of methods. The files an app downloads (images, videos) are the Flutter starter's [resources' cache](../spring-boot-starter-flutter/resources.md), `spring.flutter.resources.cache.*`: a folder of its own beside `spring/caches/` with a limit of its own. Neither counts towards the other's limit, and clearing one leaves the other.
- **Values.** As JSON through the application's `ObjectMapper`: `String`, numbers, `bool`, `null`, an object the mapper reads (`@Introspected()` or a JSON serializer), a `List`, `Set` or `Map<String, …>` of those, and a `Resource` with an address, kept as its address (a file the Flutter starter keeps is one copy for both). Another value is not kept, and the cache logs it once; an empty collection is not kept either, its element type being unknown.
- **Answers later.** The caches are `AsyncCache`s (Spring's `Cache.retrieve`): the interceptor waits for them in a method that returns a `Future`. A method that does not return one on such a cache is a start-up error naming the method and the cache.
- **Several stores.** `CompositeCacheManager`, Spring's, asks several managers for a cache name. `LayeredCacheManager`, not Spring's, puts a fast cache in front of slower ones: a hit in a slower one is copied into the faster ones, a put and an evict go to every layer.

```dart
@Configuration()
class CacheConfig {
  @Bean()
  @Primary()
  CacheManager memory() => InMemoryCacheManager(
        defaultSpec: const CacheSpec(timeToLive: Duration(minutes: 1)),
      );

  @Bean()
  CacheManager disk(CacheStore store, ObjectMapper mapper,
          Introspector introspector) =>
      DiskCacheManager(store: store, mapper: mapper,
          introspector: introspector, timeToLive: const Duration(days: 1));

  @Bean()
  CacheManager layered(CacheManager memory, CacheManager disk) =>
      LayeredCacheManager([memory, disk]);
}
```

- **A file as a key.** A resource is equal to another by its address, as in Spring: a result made from a file that changed at the same address stays until it expires. With `spring.cache.resource-version: true` a key made of a resource the Flutter starter keeps is its address and the version of its content (a digest), so a new file is a new key. Off by default: the digest is of the whole file.

## Properties

| Key | Default | Meaning |
|---|---|---|
| `spring.cache.type` | `simple` | `disk` keeps the entries on disk |
| `spring.cache.disk.time-to-live` | none | How long an entry lives, by the wall clock |
| `spring.cache.disk.caches.<name>.time-to-live` | the global one | The same, for one cache |
| `spring.cache.disk.max-size` | none | The most bytes each cache keeps |
| `spring.cache.disk.directory` | `.spring/cache` | The folder where no `CacheStore` bean gives a place |
| `spring.cache.disk.version` | none | The version entries are written by and read for |
| `spring.cache.resource-version` | `false` | A resource as a key by its content's version |
