Getting Started

Cluster Bootstrap Sequence

From cold start to accepting writes in seconds.

Starting Nodes

node-1:5701

FOLLOWER

node-2:5702

FOLLOWER

node-3:5703

FOLLOWER

Prerequisites

• Java 25+ for the server (--enable-preview is required — virtual threads).
• Java 17+ is enough for the client SDK.
• Maven 3.9+.

java --version     # expect 25 or higher on the server

Build

git clone <repository>
cd DistributedCache
mvn clean install -DskipTests

Modules:

Module	Purpose
loom-common	Wire protocol (MessageType, MessageCodec), Kryo serialization.
loom-server	TCP server, Raft, data structures, WAL, snapshots, CP subsystem.
loom-client	Client SDK: smart routing, near cache, pooling, retry.
loom-spring-boot	Spring Boot 4.0.5 auto-configuration + REST controllers.
loom-integration-tests	Multi-node IT suite with Jepsen-style chaos harness.

Server-only build: mvn -pl loom-server,loom-common -am clean package -DskipTests.

Path 1 — Embedded, single JVM

import com.loomcache.server.embedded.EmbeddedLoomCache;
import com.loomcache.client.LoomClient;
import com.loomcache.client.LoomMap;

EmbeddedLoomCache cache = EmbeddedLoomCache.builder()
    .nodeId("embedded-1")
    .port(5701)
    .dataDir("./embedded-data")
    .build();
cache.start();

LoomClient client = cache.client();
LoomMap<String, String> map = client.getMap("users");
map.put("alice", "Alice");
System.out.println(map.get("alice"));

cache.stop();

Path 2 — 3-node Docker cluster

docker-compose up -d
docker-compose ps

Default port mapping:

Service	Cluster → host	Metrics → host
loomcache-node1	7654:7654	9090:9090
loomcache-node2	7655:7654	9091:9090
loomcache-node3	7656:7654	9092:9090

See Deployment (Docker/K8s) for production layouts.

Connect a client

LoomClient client = LoomClient.builder()
    .addSeed("localhost:7654")
    .addSeed("localhost:7655")
    .addSeed("localhost:7656")
    .requestTimeout(Duration.ofSeconds(15))
    .maxRetries(3)
    .build();
client.connect();

First operations

LoomMap<String, String> users = client.getMap("users");
users.put("alice", "Alice");

LoomQueue<String> tasks = client.getQueue("tasks");
tasks.offer("send-welcome-email");

LoomAtomicLong counter = client.consistencySubsystem().getAtomicLong("hits");
counter.incrementAndGet();

LoomTopic<String> events = client.getTopic("events", String.class);
int sub = events.subscribe(m -> System.out.println("got: " + m));
events.publish("hello");
events.unsubscribe(sub);

client.close();

Spring Boot (optional)

loomcache:
  cluster:
    seeds: [127.0.0.1:5701, 127.0.0.1:5702, 127.0.0.1:5703]
  client:
    connect-timeout-ms: 5000
    request-timeout-ms: 3000

The starter registers LoomClient and AsyncLoomClient beans. Set loomcache.server.enabled=true to run an embedded CacheNode inside the Spring Boot application.

Next

• Architecture overview — modules and request flow.
• Configuration reference — every property.
• Client API — the full client surface.
• Spring Boot integration — auto-configuration details.