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:

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:

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:

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.

@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

// "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.

// 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
@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)

@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). CacheManagerCustomizer is not generic. CachingConfigurer methods must not be @Bean methods.

See also