DAC Cache integration guide

Set it up in four steps

You need a Spring Boot service, a database repository, and a Redis or Valkey connection. For a local run, this is enough: docker run -p 6379:6379 valkey/valkey:8.0.

Step 1 — Add one dependency

<dependency>
    <groupId>com.juliusbaer.dac</groupId>
    <artifactId>cache-starter</artifactId>
</dependency>

And one build-time dependency, so the cache records are generated from your entities (Step 3). It is provided and goes on the compiler's processor path, the same way Lombok does:

<dependency>
    <groupId>com.juliusbaer.dac</groupId>
    <artifactId>cache-snapshot-processor</artifactId>
    <scope>provided</scope>
</dependency>

<plugin>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></path>
            <path><groupId>com.juliusbaer.dac</groupId><artifactId>cache-snapshot-processor</artifactId></path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Step 2 — Point at Redis

spring:
  data:
    redis:
      host: localhost
      connect-timeout: 250ms # example: fit these limits to your request SLA
      timeout: 500ms

Step 3 — Cache your first table

Pick a small reference table — one that changes rarely. Put one annotation on its JPA entity; that is the entire cache configuration. The build generates ProductCategorySnapshot, the record that is stored in the cache:

@Entity
@CacheSnapshot(region = "productCategories",
        indexes = @SnapshotIndex(name = "byName", property = "name"))
public class ProductCategory {
    @Id private Long id;
    private String name;
    private String description;
    // getters
}

Read it anywhere — no repository call:

masterData.lookup(ProductCategorySnapshot.class).byIndex("byName", "Bonds");

The complete example is in the static data guide. The record can also be written by hand — see Generating snapshots.

Step 4 — Cache data that changes (with a TTL)

Do not copy a large transaction table into the cache without a limit. Define how one missing row is loaded and how long it stays cached. You can then load a bounded default window, or populate the cache when a relevant application event occurs.

# application.yaml — change the default through TRANSACTION_CACHE_TTL
dac:
  cache:
    regions:
      transactions:
        l2-ttl: ${TRANSACTION_CACHE_TTL:30s}

@Bean
CacheRegionConfig<String, TransactionSnapshot> transactions(TransactionLedger ledger) {
    return CacheRegionConfig.transactional("transactions", String.class, TransactionSnapshot.class)
            .loader(ledger)                     // cache miss -> one database read
            .build();                           // TTL comes from application.yaml above
}

@Bean
CacheWriteBinding<Transaction> transactionWrites() {
    // Hibernate observes normal JPA insert, update and delete operations.
    return CacheWriteBinding.evict(
            "transactions", Transaction.class, Transaction::getId);
}

// Recommended: warm the bounded working set before accepting traffic.
region.warm(transactionRepository.findCreatedSince(cutoff));

The starter applies dac.cache.regions.transactions.l2-ttl to this region at startup. The bean defines the loader and region behaviour, while each environment controls the TTL without rebuilding the application.

When the application already uses Spring Data JPA with Hibernate, the write binding activates automatically. Repository and entity-manager writes need no cache call in the service: the key is evicted only after a successful commit, while a rollback leaves the cached value unchanged.

Next references

• See everything live — every behaviour above runs on the separate live initializer page, with the data shown as tables and a live log.
• Where the cache sits in the network — How it fits into an application (DMZ, BareNet, database, third-party systems).
• Static data — follow the static data guide.
• Transactional data — follow the transactional data guide.
• Keeping caches fresh — refresh endpoints and event-driven refresh for when the source changes.

Where the code lives

The library is developed in the client-notification-handler repository under dac/:

The library will move into a common GitLab repository with its own release cycle, so every team can consume it without depending on this repo. The module names and Maven coordinates (com.juliusbaer.dac) stay the same — only the repo links above will change when that happens.

How a cache read works

Every cached read follows the same path. A hit returns immediately. A miss moves to the next step. Only the final miss reaches your database or external source.

Compatibility

The current release has one tested baseline. Use these versions unless the library is updated and successfully tested with another combination.

How it fits into an application

DAC Cache is a library inside your service, not another application to deploy. Each service instance keeps a small local cache (L1). All instances share Redis or Valkey (L2). If neither has the value, your loader reads it from the database or another source.

Two deployments, same library. Pick the one that matches where your service runs.

The recommended application pattern

Use the following as the default. It gives teams one clear path while keeping the database or external system as the source of truth.

Failures and instance lifecycle

Secondary-index lookups cannot rebuild an index from one primary-key loader call. If Redis is unavailable, they return a cache miss so the application facade can run its indexed source query. Keep that source fallback in the facade.

Static data guide

Use static caching for a small reference table that can be loaded as one complete snapshot—for example countries, status codes or product categories. Each service instance keeps a temporary L1 copy, Redis or Valkey holds the shared snapshot, and the repository remains the fallback source.

What a snapshot is — and what it is not

Every value in the cache is a snapshot: a small, read-only copy of one database row, stored as JSON in Redis and as an object in each instance's memory. Both static and transactional regions cache snapshots — the difference is only how they are loaded (whole table at once, or one row when first read).

Why the cache stores a snapshot and not the JPA entity

• An entity is tied to a database session. It carries proxies and lazy relations that only work while that session is open. Serialize one into Redis and read it back in another instance and it fails or drags along data nobody asked for. A snapshot is plain fields only.
• An entity can be modified. Setters, and Hibernate tracking every change. A cached value is shared by every thread in the instance and by every instance; if one caller could change it, all readers would see the change. A snapshot is a Java record: it cannot be modified after it is created.
• An entity has the shape of the table. A snapshot has the shape the readers need — usually flatter, sometimes with a value pulled from a related table, never with fields nobody reads. This keeps Redis small and reads fast.

The rules a snapshot follows

Changing a snapshot safely

Instances are redeployed one at a time, so for a while old and new code read the same Redis values. Other applications may share a region too. This makes the snapshot class a contract, and there are two kinds of change:

• Adding a field — safe. Old readers ignore the new field; new readers see null for values written by old code until the entry is reloaded or expires. For static regions the next reload writes a complete new version.
• Renaming, removing or changing the type of a field — a breaking change. Treat it like an API change: give the region a new name (which is a new set of keys) or reload it in the same deployment as the code change, and never do it on a region another application reads.

Not the same as the "Memento" design pattern

Because the name is "snapshot", the GoF Memento pattern comes to mind. It is a different thing. A memento is a saved copy of an object's state made so the same object can be restored to it later — undo, rollback. Our snapshots are never restored into anything: data flows one way, from the database through the loader into the cache and out to readers. When the source changes we do not put the old snapshot back, we evict the entry or load a new one from the database. The right description of what we cache is: an immutable read-only copy of a row (a value object), produced by a mapping method, that the cache stores under a key — the same idea as a "read model" or "projection" in systems that separate writes from reads.

Writing these records by hand for every entity is repetitive; the cache-snapshot-processor module generates them from the entity class at compile time. See Generating snapshots at the end of this page.

Transactional data guide

Use transactional caching for data that changes continuously. Load a bounded useful set, retain the one-row database loader for an unexpected miss, and register one Hibernate write binding for the entity. Normal JPA inserts, updates and deletes then evict the affected key after commit. A relevant application event can select rows when a time window is unsuitable.

Settings shared by both data types

Tuning without code changes

Keep safe defaults in code. Override sizes, expiry times and refresh schedules in application.yaml when an environment needs different values:

dac:
  cache:
    # refresh-cron: "0 */5 * * * *"     # scheduled refresh of all static regions
    regions:
      productCategories:
        l1-max-size: 5000
        startup: reload-if-stale        # reload at startup when the copy is older than…
        max-snapshot-age: 24h
      transactions:
        l1-max-size: 1000
        l2-ttl: ${TRANSACTION_CACHE_TTL:5m}
        negative-ttl: ${TRANSACTION_NEGATIVE_TTL:30s}

The values declared in Java are safe defaults. The YAML values above win at startup, so each environment can tune the TTL and size without rebuilding the application.

Try it in the live initializer →

Shared rules and optional behaviours

You do not need every feature for every table. Start with the simplest option that keeps your data correct, then add another only when there is a clear reason.

Static data: preloaded and versioned

Use this for a small table that changes rarely. Load the whole table at startup. Reads then use the cached snapshot by id or by an index such as product code. When the source changes, load a new snapshot and switch to it only after the load succeeds.

Try it in the live initializer →

Refresh & partial refresh

A database change does not magically change a cached copy. Call the refresh endpoint when you want to reload one static region, or refresh all static regions together.

Try it in the live initializer →

Event-driven refresh

Use a refresh event when another service or batch job changes the source. The event only needs a region name and key. One instance reloads that row and the other instances drop their old local copy. Redis Streams keeps the event until it succeeds; a failed refresh remains pending for retry. If the producer fails before appending the event, Redis has nothing to deliver, so TTL or a scheduled reload is still required. Use an outbox when the source commit and event must be guaranteed together.

Try it in the live initializer →

Loading transactional data

Warm the bounded working set expected to receive traffic. The per-key loader is a correctness fallback: if a row was not warmed, the first read gets it from the database and caches it. When a time window is not useful, let a relevant application event select and cache the required rows. In this initializer, every cached row expires after 30 seconds; after that, the next read loads it again.

Try it in the live initializer →

How transactional data stays fresh

After data changes, use the first option that fits the write path. Keep TTL as a fallback, not as the main refresh method.

Try mechanisms 1, 2 and 5 in Staleness & eviction, mechanism 3 in Event-driven refresh, and mechanism 4 in Batched writes.

Choose a safe cache key

Use the same stable identifier that your database uses for the row.

• Good: a primary key or stable business id such as TX-1001.
• Avoid: names, statuses or any value that may change.
• Keep personal data out of keys: keys appear in Redis, logs and refresh events.
• Need another lookup? Add a secondary index instead of building a hand-made composite key.

Caching "not found"

If clients repeatedly ask for an id that does not exist, remember that result briefly. In this initializer, the cache remembers “not found” for 15 seconds, so the database is asked only once.

Try it in the live initializer →

Staleness & eviction

Stale data means the database changed but the cached copy did not. Fix the write path: after the database commit, evict the key or publish a refresh event. The next read then gets the new value.

Try it in the live initializer →

Write policies: write-behind, write-through, write-around

Choose one write rule per region:

• Write-through: update the database now, then update the cache. This is the easiest option to reason about.
• Write-around: update the database and evict the cache. The next read reloads it.
• Write-behind: update the cache now and batch database writes in the background. Use this only when rapid updates make immediate writes too expensive.
• None: this region is read-only from this application's point of view.

Try it in the live initializer →

Leader election

Some background work should run once, even when several service instances are running. The instances use a short Redis lock to choose an owner. If that instance stops, another takes over.

Try it in the live initializer →

Statistics

Watch hits, misses, database loads and evictions. These numbers tell you whether warming and TTL settings are helping. They are also available as dac.cache.* actuator metrics.

Try it in the live initializer →

Installing Redis/Valkey on premise

The cache needs one shared Redis-compatible store in each environment. Valkey is the recommended option and works with Spring's existing spring.data.redis.* settings.

Choose the setup that matches where the application runs:

1. Local development

The initializer works without an installation. To test against a real Valkey instance, run:

docker run -d -p 6379:6379 valkey/valkey:8.0

Then set spring.data.redis.host: localhost. This single-node setup is only for local development.

2. On-premise Kubernetes — the CNH high-availability chart

For shared environments, this repository provides a Helm chart: dac/pkgs/valkey-sentinel-chart — the same chart used by the CNH on-premise test environment. It gives you:

• Three Valkey nodes: one primary accepts writes and two replicas keep copies.
• Automatic failover: Sentinel promotes a replica if the primary stops.
• Disk persistence: the append-only journal protects queued writes and refresh events during restarts.
• Optional tools: HAProxy for clients outside the cluster and a small UI for inspecting keys.

Installation:

helm install valkey dac/pkgs/valkey-sentinel-chart \
  --namespace valkey --create-namespace \
  --set auth.password=<a-strong-password> \
  --set persistence.size=2Gi

Applications connect through Sentinel, so they can find the current primary after a failover:

spring:
  data:
    redis:
      sentinel:
        master: mymaster
        nodes: valkey:26379
      password: <the valkey password>

The settings most installations touch:

3. Production checks

• Memory: allow headroom, set maxmemory, and keep the policy at noeviction. The library already manages entry expiry.
• Durability: keep the append-only journal enabled when using write-behind or refresh events.
• Security. Always set a password; never place client-identifying data in keys (see Choosing keys); add TLS where the network zone requires it.
• Sharing: one store can serve several applications because each application gets its own {application name}:cache key prefix.

Start with replication and Sentinel. Move to Redis Cluster sharding only when one node can no longer hold the data or handle the write rate.

Generating snapshots

Every cached entity needs a snapshot record and a from(entity) method. The code is simple but repetitive, and it has to be kept in step with the entity. The module cache-snapshot-processor writes it for you at compile time, the way Lombok or MapStruct do. It is an annotation processor: it runs inside javac and ships nothing at run time.

What you write

@Entity
@Data                                                    // Lombok getters are fine
@CacheSnapshot(
        region  = "productCategories",
        type    = RegionKind.STATIC,                     // or TRANSACTIONAL
        indexes = @SnapshotIndex(name = "byName", property = "name"))
public class ProductCategory {

    @Id private Long id;
    private String name;
    private String description;

    @SnapshotIgnore                                      // stays out of the cache
    private String internalComment;

    @ManyToOne(fetch = FetchType.LAZY)                   // becomes familyId
    private ProductFamily family;

    @OneToMany(mappedBy = "category")                    // collections are always left out
    private List<ProductTag> tags;
}

What the processor generates

// ProductCategorySnapshot.java — in target/generated-sources, do not edit
@MasterDataRegion(name = "productCategories", entity = ProductCategory.class,
        indexes = @RegionIndex(name = "byName", property = "name"))
public record ProductCategorySnapshot(
        Long id, String name, String description,
        Long familyId) {                                 // relation flattened to its id

    public static final String REGION = "productCategories";

    public static ProductCategorySnapshot from(ProductCategory entity) { ... }
}

The record lands in the entity's package. For a static region it carries @MasterDataRegion, so declaring the cache needs no further code. For a transactional region it is a plain record; you still write the region config and loader as shown above.

The rules

Computed keys: an example

public interface EventTemplateKeys {
    Long alertChannelMappingId();                        // satisfied by the record's accessors
    Long eventSegmentsMappingId();
    LanguageCode language();

    default String channelSegmentLanguageKey() {         // an index can point at this
        return alertChannelMappingId() + "|" + eventSegmentsMappingId() + "|" + language();
    }
}

@CacheSnapshot(region = "eventTemplate", implement = EventTemplateKeys.class,
        indexes = @SnapshotIndex(name = "byChannelSegmentLanguage", property = "channelSegmentLanguageKey"),
        paths   = @SnapshotPath(name = "eventType", path = "eventSegmentsMapping.eventConfiguration.eventType"))
public class EventTemplate { ... }

Wiring it into a build

<!-- the annotations: compile time only, like Lombok -->
<dependency>
  <groupId>com.juliusbaer.dac</groupId>
  <artifactId>cache-snapshot-processor</artifactId>
  <scope>provided</scope>
</dependency>
<!-- @MasterDataRegion on the generated static records -->
<dependency>
  <groupId>com.juliusbaer.dac</groupId>
  <artifactId>cache-masterdata-starter</artifactId>
</dependency>

<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <annotationProcessorPaths>
      <path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></path>
      <path><groupId>com.juliusbaer.dac</groupId><artifactId>cache-snapshot-processor</artifactId></path>
    </annotationProcessorPaths>
  </configuration>
</plugin>

Put the processor in the module that holds the entities. If a snapshot was written by hand before, delete it in the same change — two classes declaring the same region name fail at start-up.

Why compile time, and not runtime

• You can read the generated code. It is normal Java in target/generated-sources, steps through in a debugger, and needs no agent or bytecode manipulation at run time.
• Mistakes surface at build time. A missing id, an index on a property that does not exist, or a path that cannot be resolved fails the compilation with a clear message.
• Nothing extra ships. The processor is a build-time dependency only.
• It stays optional. Hand-written snapshots keep working unchanged; a team can adopt the annotation entity by entity.

Not done yet

• Generated write bindings for transactional entities (today: CacheWriteBinding by hand).
• A build-time check that a region name is unique across the whole application.
• A build-time description of each record's shape, so a later build can flag a renamed or removed field of a shared region as a breaking change.