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

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

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

@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.

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.*).

See also