Spring Boot Integration

LoomCache ships with a dedicated loom-spring-boot module providing seamless Spring Boot 4.0.0 auto-configuration. Add the dependency, write your application.yml, and Spring wires up clients, an embedded server, REST controllers, and Actuator health — all automatically.

Spring Boot Integration

Auto-configured beans, REST endpoints, and Actuator health.

application.yml
Spring Boot reads loomcache.* properties

LoomClientSync Client

AsyncLoomClientAsync Client

CacheNodeEmbedded Server

MapControllerREST /api/map

QueueControllerREST /api/queue

LockControllerREST /api/lock

CounterControllerREST /api/counter

HealthIndicatorActuator

Quick Start

Add the Dependency

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

Minimal Configuration

loomcache:
  cluster:
    node-id: node-1
    seeds:
      - 127.0.0.1:5701
      - 127.0.0.1:5702
      - 127.0.0.1:5703
  server:
    enabled: true
    port: 5701

Spring Boot auto-registers these beans:

Bean	Description
LoomClient	Synchronous client with smart routing
AsyncLoomClient	Asynchronous client with CompletableFuture
CacheNode	Embedded server (when server.enabled=true)
LoomHealthIndicator	Actuator health check

REST Controllers

The Spring Boot module auto-registers 8 REST controllers exposing all data structures over HTTP:

Controller	Base Path	Operations
MapController	/api/map	GET, PUT, DELETE, SCAN
QueueController	/api/queue	OFFER, POLL, PEEK, SIZE
SetController	/api/set	ADD, REMOVE, CONTAINS, CARD
SortedSetController	/api/sorted-set	ADD, RANK, RANGE, SCORE
TopicController	/api/topic	PUBLISH, SUBSCRIBE
LockController	/api/lock	TRYLOCK, UNLOCK
CounterController	/api/counter	INCREMENT, GET, RESET
ClusterController	/api/cluster	MEMBERS, STATUS, LEADER

Example REST Calls

# Put a value
curl -X PUT http://localhost:8080/api/map/users/alice \
  -H "Content-Type: application/json" \
  -d '"Alice Smith"'

# Get a value
curl http://localhost:8080/api/map/users/alice

# Increment a counter
curl -X POST http://localhost:8080/api/counter/requests/increment

# Check cluster status
curl http://localhost:8080/api/cluster/status

Full Configuration

loomcache:
  cluster:
    seeds:
      - 127.0.0.1:5701
      - 127.0.0.1:5702
    node-id: node-1

  client:
    connect-timeout-ms: 5000
    request-timeout-ms: 3000
    max-retries: 3
    near-cache:
      enabled: true
      max-size: 10000
      ttl-seconds: 30

  server:
    enabled: true
    port: 5701
    bind-address: 0.0.0.0
    raft:
      election-timeout-ms: 3000
      heartbeat-interval-ms: 1000
    persistence:
      enabled: true
      wal-directory: ./data
      snapshot-threshold: 10000
    eviction:
      policy: LRU
      max-entries: 100000
      max-memory-bytes: 1073741824
    failure-detection:
      phi-accrual-threshold: 8.0
      enable-adaptive-threshold: true
    discovery:
      retry-backoff-ms: 100
      max-retries: 3
      ttl-aware-caching: true
      health-check-enabled: true
      health-check-interval-ms: 30000
    network:
      max-connections: 10000
      circuit-breaker:
        enabled: true
        failure-threshold: 5
        recovery-timeout-ms: 30000
        half-open-max-requests: 3
    hot-key:
      enabled: true
      sampling-rate: 0.05
      threshold: 100
      window-seconds: 60
      max-tracked-keys: 10000

  tls:
    enabled: true
    key-store-path: /etc/loomcache/node-1.p12
    key-store-password: ${TLS_KEY_STORE_PASSWORD}
    trust-store-path: /etc/loomcache/truststore.p12
    trust-store-password: ${TLS_TRUST_STORE_PASSWORD}
    require-client-auth: true
    protocols: TLSv1.3,TLSv1.2

  auth:
    enabled: true
    gateway-trust: true
    user-header: X-Auth-User
    roles-header: X-Auth-Roles
    role-prefix: ROLE_
    roles:
      read-only:
        permissions:
          - MAP_GET
          - QUEUE_PEEK
          - COUNTER_GET
      data-writer:
        permissions:
          - MAP_GET
          - MAP_PUT
          - MAP_DELETE
          - QUEUE_PUSH
          - QUEUE_POP
      admin:
        permissions:
          - "*"

Health Indicator

The LoomHealthIndicator integrates with Spring Boot Actuator:

curl http://localhost:8080/actuator/health

{
  "status": "UP",
  "components": {
    "loomcache": {
      "status": "UP",
      "details": {
        "connectedNodes": 3,
        "leader": "node-1",
        "raftTerm": 42,
        "commitIndex": 158293
      }
    }
  }
}

Use this endpoint for Kubernetes readiness and liveness probes:

livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: 8080
  initialDelaySeconds: 10
readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: 8080
  initialDelaySeconds: 5

Write-Through Persistence

The Spring Boot module includes WriteThroughCacheStore for JPA-backed write-through caching:

@Repository
public interface CacheEntryRepository
    extends JpaRepository<CacheEntry, String> {}

Cache writes are automatically persisted to your relational database alongside Raft replication, providing dual durability.

Programmatic Access

Inject the auto-configured beans directly:

@Service
public class UserService {

    private final LoomClient loomClient;
    private final AsyncLoomClient asyncClient;

    public UserService(LoomClient loomClient,
                       AsyncLoomClient asyncClient) {
        this.loomClient = loomClient;
        this.asyncClient = asyncClient;
    }

    public String getUser(String id) {
        LoomMap<String, String> users = loomClient.getMap("users");
        return users.mapGet(id);
    }

    public CompletableFuture<Void> setUserAsync(String id, String name) {
        return asyncClient.mapPut("users", id, name);
    }
}