
# The in-memory caches

Without any setup, the starter creates the `cacheManager` bean, an `InMemoryCacheManager` (Spring's `ConcurrentMapCacheManager`). Each cache is an `InMemoryCache`, a map in the memory of the running app, created the first time an annotation names it. A time to live and a size limit, globally or per cache, come from `spring.cache.*` properties.

## Why

Most caches hold results of slow calls that are cheap to recompute after a restart. Memory is the fastest place for them and needs nothing to set up. Spring's `simple` type has no expiry or size limit and sends you to Caffeine for that; here the in-memory caches have both, so a long-running server does not grow without bound.

## Example

```properties
# lib/resources/application.properties
spring.cache.simple.time-to-live=10m
spring.cache.simple.max-size=1000
spring.cache.simple.caches.prices.time-to-live=30s     # prices go stale faster
spring.cache.simple.caches[books.byIsbn].max-size=200  # a cache name with dots
```

```dart
// An admin action: drop every cached book.
@Component()
class CacheAdmin {
  CacheAdmin(this.caches);

  final CacheManager caches;

  void clearBooks() => caches.getCache('books')?.clear();
}
```

## What the in-memory caches do

- Each cache is created the first time an annotation names it (`'books'`), unless `spring.cache.cache-names` fixes the set.
- Entries are lost when the app stops, and when the context restarts (also on a hot reload that changes beans): the cache starts empty. For results that outlive a restart, see [Caches that outlive a restart](disk-caches.md).
- Nothing expires and there is no size limit unless you set them.
- The time to live is measured on a monotonic clock, as Caffeine's ticker: setting the device's or server's clock neither keeps entries longer nor drops them early.
- Expired entries are dropped when they are read, and writes sweep out the others now and then; a cache no longer written keeps them until they are read.
- When a cache is full, the least recently used entry goes.
- `null` results are stored too: a stored `null` is a hit, as in Spring.
- One app, one isolate: the cache is not shared between processes, isolates or devices. See [With a pool of isolates](#with-a-pool-of-isolates) for a server on several.

## Properties

The default manager is built from `spring.cache.*`, only when the application declares no `CacheManager` of its own:

| Property | Default | Meaning |
|---|---|---|
| `spring.cache.type` | `generic` with `Cache` beans, else `simple` | `generic`: a `SimpleCacheManager` of the `Cache` beans (at least one needed); `simple`: caches in memory; `disk`: caches on disk that outlive a restart ([Caches that outlive a restart](disk-caches.md)); `none`: cache nothing (the annotations stay, the methods always run). Another value fails the start. |
| `spring.cache.cache-names` | empty | A fixed set of caches (`books,authors` or a YAML list); an annotation naming another cache then fails. Empty: caches are created on first use. |
| `spring.cache.simple.time-to-live` | none | How long entries live after they were written: `10m`, `30s`, `PT1H`, or milliseconds. `0` keeps nothing; a negative value fails the start. |
| `spring.cache.simple.max-size` | none | The most entries per cache. `0` keeps nothing; a negative value fails the start. |
| `spring.cache.simple.caches.<name>.time-to-live` | the global one | The same, for one cache. |
| `spring.cache.simple.caches.<name>.max-size` | the global one | The same, for one cache. |

Every per-cache value is checked at the start, whether the cache exists yet or not.

### Cache names in keys

- A cache name with dots goes in brackets, as in any Spring Boot map: `spring.cache.simple.caches[books.byIsbn].max-size=2`; in YAML the key `"[books.byIsbn]":`.
- Written plainly (`spring.cache.simple.caches.books.byIsbn.max-size`) it works too: the property is the end of the key (`max-size`, `time-to-live`, or a relaxed form: `maxSize`, `max_size`, `MAXSIZE`), the rest the cache name.
- In environment variables, as in Spring Boot: `SPRING_CACHE_SIMPLE_CACHES_BOOKS_MAX_SIZE=5` or `..._BOOKS_MAXSIZE=5`, `SPRING_CACHE_SIMPLE_CACHES_PRICES_TIME_TO_LIVE=30s`. The cache name comes out in lower case, so a name with capitals or dashes cannot be set this way; a `_` inside it is a dot here (`..._BOOKS_BYISBN_MAX_SIZE` sets the cache `books.byisbn`).

## Configured in code

Declare your own `InMemoryCacheManager` bean; the properties then no longer apply:

```dart
@Configuration()
class CacheSetup {
  @Bean()
  CacheManager cacheManager() => InMemoryCacheManager(
        cacheNames: ['books', 'prices'],                     // only these two
        defaultSpec: const CacheSpec(timeToLive: Duration(minutes: 10)),
        specs: {'prices': const CacheSpec(timeToLive: Duration(seconds: 30), maxSize: 500)},
      );
}
```

| `InMemoryCacheManager` parameter | Meaning |
|---|---|
| `cacheNames` | A fixed set of caches; without it, caches are created on demand. |
| `defaultSpec` | The `CacheSpec(timeToLive:, maxSize:)` of every cache; unlimited by default. |
| `specs` | Specs by cache name. |
| `specFor` | A function computing a spec from a cache's name. |
| `allowNullValues` | `true` by default; with `false`, storing `null` throws. |
| `clock` | A clock for tests (see [Testing](testing.md)). |

A negative `maxSize` or `timeToLive` throws an `ArgumentError`.

## Adjusting the starter's manager

- A `CacheManagerCustomizer` bean is called once with the new manager, for example to create some caches at startup. It is not generic: it gets the manager and checks its type.
- `cacheManagerFromProperties(properties, environment, caches:, customizers:)` builds the same manager as the starter, for a `CacheManager` bean of your own, such as one that wraps it.

```dart
@Bean()
CacheManager cacheManager(CacheProperties properties, Environment environment) =>
    MeteredCacheManager(cacheManagerFromProperties(properties, environment)); // your wrapper
```

## With a pool of isolates

When the web server runs a [pool of isolates](../spring-boot-starter-web/server/isolates.md) (`server.isolates.count`), every isolate has its own `CacheManager` and its own cached values.

- A value is computed once per isolate, not once for the application.
- `@CacheEvict` and `@CachePut` change the cache of the isolate that runs them. The other isolates keep their old value until it expires.
- `max-size` counts per isolate, and so does the memory of the entries.

The pool says so once, when it first adds an isolate. The starter's managers, the default in-memory one and `SimpleCacheManager`, are named in its warning as `cached values`:

```text
Each isolate keeps its own cached values in memory, and a request may reach any isolate: what one keeps the others do not see. Keep it where all of them do (a database, a shared store), or accept one copy per isolate.
```

A `CacheManager` of your own is named when it implements `IsolateLocalState`.

A cache often can live with one copy per isolate: what it holds can be computed again, and a time to live bounds how long two isolates disagree. Where a stale value is not acceptable after a change, use a [cache of your own](custom-caches.md) over a store all isolates share.

## In Spring (Java)

```properties
spring.cache.type=simple
spring.cache.cache-names=books,authors
```

`spring.cache.type` and `spring.cache.cache-names` are Spring Boot's; `type` knows `generic`, `simple`, `disk` and `none`, `disk` being this starter's own. `spring.cache.simple.*` is this starter's: in Spring Boot the time to live and size come from Caffeine or Redis (`spring.cache.caffeine.*`, `spring.cache.redis.*`).

## See also

- [All properties](properties.md)
- [Caches that outlive a restart](disk-caches.md)
- [Your own caches](custom-caches.md)
- [A pool of isolates](../spring-boot-starter-web/server/isolates.md)
- [Durations](../spring-core-dart/conversion/durations.md)
