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
# 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
// 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'), unlessspring.cache.cache-namesfixes 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.
- 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.
nullresults are stored too: a storednullis 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 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); 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=5or..._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_SIZEsets the cachebooks.byisbn).
Configured in code
Declare your own InMemoryCacheManager bean; the properties then no longer apply:
@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). |
A negative maxSize or timeToLive throws an ArgumentError.
Adjusting the starter's manager
- A
CacheManagerCustomizerbean 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 aCacheManagerbean of your own, such as one that wraps it.
@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 (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.
@CacheEvictand@CachePutchange the cache of the isolate that runs them. The other isolates keep their old value until it expires.max-sizecounts 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:
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 over a store all isolates share.
In Spring (Java)
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.*).