Skip to content
LoomCache

Getting Started

LoomCache is a production-ready distributed cache engine built from scratch in Java 25. This guide walks you through building the project, starting a 3-node cluster, and connecting your first client.

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

Section titled “Prerequisites”
  • Java 25 LTS or later
  • Maven 3.9 or later
Terminal window
java --version
# Expected: openjdk 25 or higher

Build the Project

Section titled “Build the Project”
Terminal window
mvn clean install -DskipTests

This compiles all 5 modules:

ModulePurpose
loom-commonProtocol definitions (101 message types), Kryo serialization, utilities
loom-serverRaft consensus, partition management, WAL persistence
loom-clientLoomClient SDK with smart routing, near cache, connection pooling
loom-spring-bootSpring Boot 4.0.0 auto-configuration and REST controllers
loom-integration-tests11,600+ test methods covering consensus, failover, and chaos

To build only the server and client:

Terminal window
mvn clean package -DskipTests --projects loom-server,loom-client -am

Start a 3-Node Cluster

Section titled “Start a 3-Node Cluster”

Step 1: Build the Server JAR

Section titled “Step 1: Build the Server JAR”
Terminal window
mvn clean package -DskipTests --projects loom-server -am

The fat JAR lands at loom-server/target/loom-server-*-jar-with-dependencies.jar.

Step 2: Launch Three Nodes

Section titled “Step 2: Launch Three Nodes”

Open three terminals:

Terminal 1 — Node 1:

Terminal window
java -cp loom-server/target/loom-server-*-jar-with-dependencies.jar \
  com.loomcache.server.CacheNodeMain \
  --node-id=node-1 \
  --port=5701 \
  --cluster-members=127.0.0.1:5701,127.0.0.1:5702,127.0.0.1:5703

Terminal 2 — Node 2:

Terminal window
java -cp loom-server/target/loom-server-*-jar-with-dependencies.jar \
  com.loomcache.server.CacheNodeMain \
  --node-id=node-2 \
  --port=5702 \
  --cluster-members=127.0.0.1:5701,127.0.0.1:5702,127.0.0.1:5703

Terminal 3 — Node 3:

Terminal window
java -cp loom-server/target/loom-server-*-jar-with-dependencies.jar \
  com.loomcache.server.CacheNodeMain \
  --node-id=node-3 \
  --port=5703 \
  --cluster-members=127.0.0.1:5701,127.0.0.1:5702,127.0.0.1:5703

All three nodes will discover each other, run Raft pre-vote, elect a leader, and begin accepting requests within seconds.

Connect a Client

Section titled “Connect a Client”

Add the dependency to your Maven POM:

<dependency>
    <groupId>com.loomcache</groupId>
    <artifactId>loom-client</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Synchronous Client

Section titled “Synchronous Client”
LoomClient client = LoomClient.builder()
    .addSeed("127.0.0.1:5701")
    .addSeed("127.0.0.1:5702")
    .addSeed("127.0.0.1:5703")
    .connectionTimeout(Duration.ofSeconds(5))
    .requestTimeout(Duration.ofSeconds(10))
    .build();


client.connect();
System.out.println("Connected to " + client.connectedNodes() + " nodes");

Asynchronous Client

Section titled “Asynchronous Client”
AsyncLoomClient asyncClient = new AsyncLoomClient(syncClient);


asyncClient.mapPut("myMap", "key1", "value1")
    .thenCompose(v -> asyncClient.mapGet("myMap", "key1"))
    .thenAccept(value -> System.out.println("Got: " + value))
    .join();

Quick Examples

Section titled “Quick Examples”

Distributed Map

Section titled “Distributed Map”
LoomMap<String, String> users = client.getMap("users");
users.put("alice", "Alice Smith");
String name = users.get("alice");  // "Alice Smith"

Distributed Lock

Section titled “Distributed Lock”
LoomLock lock = client.getLock("critical-section");
long fenceToken = lock.tryLock("client-1", Duration.ofSeconds(10));
try {
    // Protected critical section
} finally {
    lock.unlock("client-1", fenceToken);
}

Pipeline Batching

Section titled “Pipeline Batching”
Pipeline pipeline = client.newPipeline();
pipeline.mapPut("cache", "k1", "v1")
        .mapPut("cache", "k2", "v2")
        .mapGet("cache", "k1");
List<Object> results = pipeline.flush();  // Single round-trip

Near Cache

Section titled “Near Cache”

Enable client-side caching with server-push invalidation:

LoomClient client = LoomClient.builder()
    .addSeed("127.0.0.1:5701")
    .nearCacheEnabled(true)
    .nearCacheTtl(Duration.ofSeconds(30))
    .nearCacheMaxSize(10000)
    .build();

GET operations check the local near cache first. When data changes on the server, the near cache entry is invalidated via server push (with TTL polling as fallback).

Running Tests

Section titled “Running Tests”
Terminal window
# Fast unit tests (5-10 seconds)
mvn verify -Dtags=fast


# Full cluster and failure injection tests (1-5 minutes)
mvn verify -Dtags=cluster


# All tests including chaos and linearizability verification
mvn verify

Next Steps

Section titled “Next Steps”