Cache Management

1. Overview

The admin-service uses Hazelcast as a distributed caching layer for both Spring @Cacheable application caches and Hibernate second-level (L2) entity caches. All cache data is shared across cluster members via Hazelcast distributed maps.

2. Cache Architecture

2.1. Spring Application Caches

These caches are managed by Spring’s CacheManager backed by HazelcastCacheManager.

Cache Name TTL Purpose

userOrgAccess

300s (5 min)

Organisation access resolution for security queries

userPersonAccess

300s (5 min)

Person access resolution for security queries

2.2. Hibernate L2 Entity Cache

JPA entities are cached using HazelcastCacheRegionFactory as the Hibernate second-level cache provider.

Region Pattern TTL Purpose

za.co.idealogic.event.domain.*

3600s (1 hour)

All JPA entity data loaded from the database

2.3. Hazelcast Clustering

In production (Kubernetes), Hazelcast instances discover each other via Kubernetes service discovery. All cache maps are distributed — data written on one node is visible to all nodes.

3. Why Restarting Does Not Clear Caches

During a rolling deployment:

  1. Pod A holds cached data (including stale entries)

  2. Pod B starts and joins the Hazelcast cluster

  3. Pod B replicates cache data from Pod A

  4. Pod A terminates

  5. Pod B now holds the same stale cache data

This is by design — Hazelcast ensures high availability by replicating data across members. The only reliable way to clear stale data is to evict the cache via the API while the cluster is running.

4. Eviction Endpoints

All endpoints are under /management/cache-ops and require ROLE_ADMIN authentication (see Management API Access).

Method Endpoint Description

DELETE

/management/cache-ops/evict-all

Evict both Spring and Hibernate L2 caches cluster-wide

DELETE

/management/cache-ops/evict-spring

Evict Spring @Cacheable caches only

DELETE

/management/cache-ops/evict-hibernate

Evict Hibernate L2 entity cache regions only

GET

/management/cache-ops/status

Cache names, sizes, and Hazelcast cluster member count

Additionally, Spring Boot Actuator provides built-in cache endpoints:

Method Endpoint Description

GET

/management/caches

List all Spring caches

DELETE

/management/caches

Evict all Spring caches

DELETE

/management/caches/{name}

Evict a specific Spring cache by name
The built-in Actuator cache endpoints only cover Spring caches, not Hibernate L2 cache. Use /management/cache-ops/evict-all to clear both.

5. Operational Runbook

5.1. Scenario: Changed data in the database, application shows stale data

This is the most common scenario — you have updated records directly in the database and the application continues to serve old data.

# 1. Check current cache status
curl -H "X-API-KEY: <key>" https://<host>/management/cache-ops/status

# 2. Evict all caches (Spring + Hibernate L2)
curl -X DELETE -H "X-API-KEY: <key>" https://<host>/management/cache-ops/evict-all

# 3. Verify caches are cleared
curl -H "X-API-KEY: <key>" https://<host>/management/cache-ops/status

5.2. Scenario: Changed organisation or person link data only

If you only modified linked_person or linked_org records, you can target just the Spring security caches:

curl -X DELETE -H "X-API-KEY: <key>" https://<host>/management/cache-ops/evict-spring

5.3. Scenario: Changed entity data (events, participants, memberships, etc.)

If you modified entity tables but not security-related data:

curl -X DELETE -H "X-API-KEY: <key>" https://<host>/management/cache-ops/evict-hibernate

6. How Cluster-Wide Eviction Works

Both eviction paths propagate automatically to all cluster members:

  • Spring caches: Cache.clear() calls Hazelcast IMap.evictAll() which is a distributed operation

  • Hibernate L2: SessionFactory.getCache().evictAllRegions() delegates to Hazelcast map operations

There is no need to call each pod individually. A single API call to any cluster member clears the cache across all members.