Distributed caches

Understand value types, namespaces, and token-based conditional operations.

master · 1.0.0-SNAPSHOT / Reviewed 2026-10-29

Types and namespaces

DistributedCacheFactory creates DistributedCache instances bound to a business namespace and value type. Every application sharing a namespace must agree on types and serialization. Encode environment or tenant scope into the namespace, or use separate backends.

Asynchronous and conditional operations

Operations return Future. A get miss returns null, put overwrites unconditionally, and putIfAbsent inserts only on a miss. Renewal and conditional removal use tokens to identify writes. Tokens are not ordered fencing versions.

CACHE.md / excerpt

DistributedCacheFactory factory = new InMemoryDistributedCacheFactory();
DistributedCache<RoomState> rooms = factory.create("room", RoomState.class);
CacheEntry<RoomState> entry = rooms.put("123", state, Duration.ofSeconds(30)).join();
CacheEntry<RoomState> current = rooms.get("123").join();
rooms.renew(entry, Duration.ofSeconds(30)).whenComplete((renewed, error) -> { });
rooms.remove(entry).whenComplete((removed, error) -> { });

Source excerpt / Read with the complete example and environment configuration

Caching and ownership

Positive local reads are disabled by default. Account for staleness and clock skew when enabling them. Concurrent getIfAbsent computations may run more than once, so the mapping function must not block or initialize external resources.

Source reference

This guide is based on the following source or module documentation. Repository access is required.

nextrix-j/nextrix-cluster/nextrix-cluster-core/CACHE.md

PreviousDiscovery and routing →NextEntity placement →