Lifecycle, failures, and operations
Latest stable Based on Bluetape4k release 1.11.0
SessionFactory owns resources
Section titled “SessionFactory owns resources”On prepareForUse, Hibernate validates settings and the codec, creates a RedisClient, applies RESP3 when enabled, assigns the client, and registers it with ShutdownQueue.
Shutdown order matters:
- Close every region Near Cache and tracking connection.
- Clear the region map.
- Shut down and null the shared
RedisClient.
Closing the client first would leave caches trying to clean up through a stopped client. StorageAccess.release() is intentionally a no-op because RegionFactory owns shared caches. Close the SessionFactory explicitly to run this lifecycle.
Convert cache failures into database fallback
Section titled “Convert cache failures into database fallback”| Operation | Result after cache failure |
|---|---|
getFromCache | Warn and return null; Hibernate reads the database |
putIntoCache | Warn and ignore; transaction continues |
contains | Warn and return false |
| Key or region eviction | Warn and ignore |
This prevents a Redis outage from directly failing a business transaction. It can instead create a miss storm against the database or leave stale local entries after failed eviction. Correlate cache errors with database-pool pressure.
Eviction scope
Section titled “Eviction scope”evictData(key) removes L1 state and calls Redis UNLINK. Region-wide evictData() clears L1, scans ${regionName}:*, and unlinks batches.
clearAll() is not constant-time. Large regions need multiple scan round trips. Avoid routine global eviction; plan namespace or version transitions for schema and serialization changes.
Operational signals
Section titled “Operational signals”- Hibernate second-level hits, misses, and puts
- Per-region
CacheRegionStatistics - Query-cache and update-timestamps activity
- Caffeine size and hit rate with stats enabled
- Redis latency, errors, reconnects, and connections
- Database latency and pool active or pending counts
- Region eviction duration and deleted-key count
A high hit rate does not compensate for stale reads or a fallback overload. Compare p95/p99, database load, and correctness against a cache-disabled baseline.
Failure drills
Section titled “Failure drills”Stop Redis briefly and verify database fallback, pool capacity, and repopulation after recovery. Modify a key through another process to verify RESP3 invalidation. Before changing codecs, prove backward readability or prepare a bounded region-eviction procedure.