Data plane — the cache facade

The data plane is the part of the library your application touches, and AbstractCache is its primary entry point: the class an application subclasses to own a region. It replaces the @Bean CacheRegionConfig plus hand-written lookup pattern with one typed class that registers its own region and carries the cache-plane-off fallback, the domain flag, the transaction guards and the logging context on every call. Underneath it sits the cache plane (the engine) — the tiers, versions and machinery your code never talks to directly.

Concept

A facade is three things put together:

1. A RegionBinding — a pure description of the region: its name, key and value types, kind (static or transactional), default TTL, secondary indexes, optional domain and what each row belongs to. It has no Spring and no engine in it, which is why a generated snapshot can carry one as a constant.
2. A CacheSupport — the facade's only link to the outside: "give me this region if it exists and is loaded", "is this domain on", "is there a TTL override", "run this read in a read-only transaction", "run this write after commit". Spring provides SpringCacheSupport; tests use CacheSupport.none().
3. Your subclass — names the binding, optionally overrides a hook (loader(), writer(), customise(), loadFromSource()…) and adds the domain-specific read methods your service calls.

At startup FacadeRegionConfigSource collects every AbstractCache bean, asks each for its regionConfig() and hands the result to the engine. An explicit @Bean CacheRegionConfig with the same region name always wins, so facades can be introduced next to existing configuration without conflict.

The minimal facade

A region that is loaded by the master-data starter (a JPA entity with @CacheSnapshot) needs nothing but the binding and the read methods you want to expose. This is the whole class for eventConfig in indc-core:

@Component
public class EventConfigurationCache extends AbstractCache<Long, EventConfigurationSnapshot> {

    private final EventConfigurationRepository repository;

    public EventConfigurationCache(CacheSupport support, EventConfigurationRepository repository) {
        super(EventConfigurationSnapshot.BINDING, support);
        this.repository = repository;
    }

    public Optional<EventConfigurationSnapshot> byEventType(String eventType) {
        return byIndex("byEventType", eventType)
                .or(() -> repository.findByEventType(eventType).map(EventConfigurationSnapshot::from));
    }
}

When the region is loaded, byIndex answers from L1 or L2. When it is not — engine off, Redis down, or a pod that has not attached to a version yet — byIndex returns empty and the .or(…) branch runs the indexed query. The service that calls byEventType never knows which happened.

Describing a region: RegionBinding

Hand-build a binding when the value is not a generated snapshot — a DTO from an external system, a record you wrote, a wrapper around a list:

@Component
public class IdmUserCache extends AbstractCache<String, User> {

    static final RegionBinding<String, User> BINDING = RegionBinding
            .transactional("idmUsers", String.class, User.class)
            .ttl(Duration.ofMinutes(30))
            .domain("idm-user", true)
            .localFallback(1_000)
            .build();

    public IdmUserCache(CacheSupport support) {
        super(BINDING, support);
    }
}

Reading

Every read passes its result through afterRead(key, value) before returning it — the hook AbstractDacCache uses to enforce entitlements. A null key or index value always returns empty without touching anything.

Read-through or cache-aside?

If the subclass overrides loader(), the region is read-through: the engine calls the loader on a miss, inside one pod, and the others pick the value up from L2. If it does not, the region is cache-aside and the application supplies the value with getOrLoad. Use cache-aside when the source call needs request-scoped context — an HTTP header, the caller's token — that a loader bean would not have:

public User getUsersById(String userId) {
    return idmUserCache
            .getOrLoad(userId, () -> fetch(() -> jbIdmWebClient.getUsersById(userId, getHttpHeaders())))
            .orElse(null);
}

Writing and refreshing

Hooks

A complete transactional facade with a loader, a writer and write-behind batching — the transactions region from the live initializer:

@Override
protected Optional<CacheLoader<String, TransactionSnapshot>> loader() {
    return Optional.of(ledger);
}

@Override
protected Optional<CacheWriter<String, TransactionSnapshot>> writer() {
    return Optional.of(ledger);
}

@Override
protected CacheRegionConfig.Builder<String, TransactionSnapshot> customise(
        CacheRegionConfig.Builder<String, TransactionSnapshot> builder) {
    return builder
            .write(WritePolicy.WRITE_BEHIND)
            .writeBehind(WriteBehindOptions.builder().flushEvery(Duration.ofSeconds(2)).coalesceByKey().build())
            .l1Ttl(Duration.ofSeconds(30))
            .negativeTtl(Duration.ofSeconds(15));
}

What the facade guarantees

• It trusts only loaded regions. region() filters on CacheRegion.isLoaded(), so a static region with no live version is treated as absent. A non-leader pod that starts before the first snapshot is published reads from its source instead of from nothing.
• Source reads run read-only. CacheSupport.readFromSource wraps every fallback in a read-only TransactionTemplate that joins an active transaction and opens a short one otherwise, so lazy relations in from(entity) are safe.
• Cache writes wait for commit. put, remove and refreshKey go through afterCommit.
• Domain off means source. A binding with a domain whose flag is off behaves exactly as if the engine were off — and skips the local fallback too, so "off" really means "every read goes to the source".
• Every call is logged in context. Operation, region and domain go into the MDC for the duration of the call.
• A static region is never patched. put() on a static binding is a no-op with a warning.

Testing a facade

A facade with CacheSupport.none() has no region and no domain — every read goes to the source path, which is usually what a unit test of the surrounding service wants:

@Spy
private IdmUserCache idmUserCache = new IdmUserCache(CacheSupport.none());

To test the cached path, build a DacCacheManager on an embedded backbone and pass a CacheSupport that returns its region — FacadeTestSupport in cache-core's tests shows the pattern.

Migrating from engine beans or Spring @Cacheable

The regions reference lists every facade CNH runs today, including the eight external-lookup caches that replaced indc-core's Spring cache configuration.