
# Your own caches

The annotations talk only to two interfaces, `CacheManager` (find a cache by name) and `Cache` (one cache: `get`, `put`, `evict`, `clear`), so anything can stand behind them: a file, a key-value database, a cache per tenant. Declare a `CacheManager` bean and the starter's one steps aside.

## Why

The in-memory caches are lost at a restart and are not shared between instances. A Flutter app may want cached data to survive a restart; a cluster may want one shared cache. The same `@Cacheable` methods keep working; only the storage changes.

## Example

Entries kept in a key-value store as JSON, mixed with an in-memory cache:

```dart
import 'dart:convert';

/// Any synchronous key-value storage: a file, a key-value database...
abstract interface class KeyValueStore {
  String? read(String key);
  void write(String key, String value);
  void delete(String key);
  void deleteAll({required String prefix});
}

/// Entries kept in the store as JSON, so they survive a restart.
final class StoreCache with CacheDefaults implements Cache {
  StoreCache(this.name, this.store);

  @override
  final String name;
  final KeyValueStore store;

  String _key(Object? key) => '$name:$key';

  @override
  ValueWrapper? get(Object? key) => switch (store.read(_key(key))) {
        null => null,                                 // a miss: the method runs
        final json => ValueWrapper(jsonDecode(json)), // a hit (also a stored null)
      };

  @override
  void put(Object? key, Object? value) => store.write(_key(key), jsonEncode(value));

  @override
  void evict(Object? key) => store.delete(_key(key));

  @override
  void clear() => store.deleteAll(prefix: '$name:');
}

@Configuration()
class CacheSetup {
  @Bean()
  CacheManager cacheManager(KeyValueStore store) => SimpleCacheManager([
        StoreCache('books', store),   // kept in the store
        InMemoryCache('prices'),      // in memory
      ]);
}
```

## The interfaces

| Type | What it does | Built in |
|---|---|---|
| `CacheManager` | `getCache(name)`, `cacheNames`. | `InMemoryCacheManager`, `SimpleCacheManager`, `NoOpCacheManager` |
| `Cache` | `name`, `get`, `put`, `putIfAbsent`, `evict`, `evictIfPresent`, `clear`, `invalidate`. | `InMemoryCache`, `NoOpCache` |
| `CacheDefaults` (mixin) | Derives `putIfAbsent`, `evictIfPresent` and `invalidate` from the four others. | |

What to keep in mind:

- **Return `ValueWrapper` for a hit and `null` for a miss.** `ValueWrapper(null)` is a cached `null`; returning plain `null` makes the method run again.
- **Keys** are the method arguments (one argument: the argument itself; several: a `SimpleKey`), or what `key:` computes. A store that needs strings must turn them into strings: `'$key'` works for strings, numbers and `SimpleKey`; for your own classes override `toString`, or set `key: '#isbn'`.
- **Values** are whatever the methods return. A store outside memory must serialize them: JSON for maps, lists, strings and numbers; your classes need `toJson` / `fromJson`.
- **`invalidate()`** of `CacheDefaults` always returns `true`, also for an empty cache. The annotations never call it.
- **The `Cache` interface is synchronous**, as in Spring. For an asynchronous store (SQLite, `shared_preferences`, a server), keep entries in memory, load the stored ones in the background (until then calls are misses: the methods simply run) and write changes back in the background with `unawaited(...)`.
- **Errors** thrown by your cache reach the caller of the cached method, unless a `CacheErrorHandler` says otherwise (below).

## Caches created on demand

`SimpleCacheManager` knows only the caches it was given: `@Cacheable('other')` then fails with "Cannot find cache named 'other'". To create caches when they are first named, implement `CacheManager`:

```dart
final class StoreCacheManager implements CacheManager {
  StoreCacheManager(this.store);

  final KeyValueStore store;
  final _caches = <String, Cache>{};

  @override
  Cache? getCache(String name) => _caches.putIfAbsent(name, () => StoreCache(name, store));

  @override
  Iterable<String> get cacheNames => _caches.keys;
}
```

With `spring.cache.type=generic` (the default when `Cache` beans exist), the starter makes a `SimpleCacheManager` of your `Cache` beans.

## Several managers

Keep the main manager for most methods and use another for some: give the other one a name, hide it from injection by type, and name it in the annotation.

```dart
@Configuration()
class CacheSetup {
  // Sessions are kept in the store; everything else stays in memory.
  @Bean(autowireCandidate: false)
  CacheManager sessionCaches(KeyValueStore store) =>
      SimpleCacheManager([StoreCache('sessions', store)]);
}

@Cacheable('sessions', cacheManager: 'sessionCaches')
Session load(String token) => sessions.load(token);
```

## Your own keys: KeyGenerator

```dart
// "978-0-00" and "978000" are the same book.
final class IsbnKeys implements KeyGenerator {
  const IsbnKeys();

  @override
  Object? generate(Object target, MethodSignature method, List<Object?> args) =>
      (args.first! as String).replaceAll('-', '');
}

@Configuration()
class Keys {
  @Bean()
  KeyGenerator isbnKeys() => const IsbnKeys();
}

@Cacheable('books', keyGenerator: 'isbnKeys')
Book find(String isbn) => load(isbn);
```

## Choosing caches per call: CacheResolver

A `CacheResolver` decides at each call which caches an operation uses, for example one cache per tenant. It sees the operation (its cache names, key...), the bean, the method and the arguments.

```dart
// Each tenant gets its own caches: "acme.books", "globex.books"...
final class TenantCacheResolver implements CacheResolver {
  TenantCacheResolver(this.manager, this.tenants);

  final CacheManager manager;
  final TenantContext tenants;

  @override
  Iterable<Cache> resolveCaches(CacheOperationInvocationContext context) => [
        for (final name in context.operation.cacheNames)
          manager.getCache('${tenants.current}.$name')!,
      ];
}

@Cacheable('books', cacheResolver: 'tenantCacheResolver')
Book find(String isbn) => load(isbn);
```

Built in: `SimpleCacheResolver(manager)` (the default: the operation's names in the manager) and `NamedCacheResolver(manager, ['audit'])` (always the same caches; the operations then need no names). As in Spring Boot, the starter's `cacheManager` backs off when a bean named `cacheResolver` exists.

## Defaults for everything: CachingConfigurer

One bean implementing `CachingConfigurer` sets the defaults of all cache operations; a method returning `null` (the default) keeps the starter's:

| Method | Default |
|---|---|
| `cacheManager()` | the `CacheManager` bean |
| `cacheResolver()` | `SimpleCacheResolver` of the cache manager |
| `keyGenerator()` | `SimpleKeyGenerator` |
| `errorHandler()` | `SimpleCacheErrorHandler`: cache errors reach the caller |

```dart
@Configuration()
class CacheSetup with CachingConfigurer {
  @override
  KeyGenerator keyGenerator() => const IsbnKeys();

  // A cache that is down: log, run the method, carry on.
  @override
  CacheErrorHandler errorHandler() => const LoggingCacheErrorHandler();
}
```

The methods are called once, when caching is first used. Return objects (or beans injected into the configuration) rather than marking the methods `@Bean`: Dart does not proxy `@Configuration` classes, so calling a `@Bean` method creates a second instance.

## Errors: CacheErrorHandler

With a `CacheErrorHandler` that does not rethrow, a failed `get` counts as a miss (the method runs) and a failed `put`, `evict` or `clear` is skipped. `LoggingCacheErrorHandler` logs them at warning level to `spring.cache` (`logStackTraces: true` adds the stack trace; `logger:` another logger). The handler's methods receive the stack trace next to the error.

## In Spring (Java)

```java
@Bean
CacheManager cacheManager() { return new SimpleCacheManager(); }
```

The interfaces are Spring's, with a smaller `Cache`: no `get(key, Class)`, `get(key, Callable)`, `retrieve` or `getNativeCache`. `retrieve` is on `AsyncCache`, for a cache whose store answers later (see [Caches that outlive a restart](disk-caches.md)). `CacheManagerCustomizer` is not generic. `CachingConfigurer` methods must not be `@Bean` methods.

## See also

- [The in-memory caches](in-memory-caches.md)
- [Annotations](annotations.md)
- [@Bean](../spring-core-dart/beans/bean-method-annotation.md)
