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:
- Return
ValueWrapperfor a hit andnullfor a miss.ValueWrapper(null)is a cachednull; returning plainnullmakes the method run again. - Keys are the method arguments (one argument: the argument itself; several: a
SimpleKey), or whatkey:computes. A store that needs strings must turn them into strings:'$key'works for strings, numbers andSimpleKey; for your own classes overridetoString, or setkey: '#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()ofCacheDefaultsalways returnstrue, also for an empty cache. The annotations never call it.- The
Cacheinterface 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 withunawaited(...). - Errors thrown by your cache reach the caller of the cached method, unless a
CacheErrorHandlersays 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:
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.