Spring Boot Integration

Spring Boot Integration

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

application.yml
Spring Boot reads loomcache.* properties

LoomCacheSync Client

LoomCacheManagerSpring Cache

Embedded NodeServer runtime

Map APIREST /api/map

Queue APIREST /api/queue

Transaction APIREST /api/transactions

Counter APIREST /api/counter

HealthIndicatorActuator

This guide covers the loom-spring-boot module, which targets Spring Boot 4.1.0. Add it to the classpath and declare a seed list; LoomAutoConfiguration wires the rest — client beans, Spring Cache, Spring Session, REST controllers, and actuator health.

Dependency

Add the module to your build:

<dependency>
    <groupId>com.loomcache</groupId>
    <artifactId>loom-spring-boot</artifactId>
    <version>${loomcache.version}</version>
</dependency>

Set loomcache.version to the published Maven Central version for tagged releases, or to the locally installed project version when testing a source checkout before using a published release.

spring-session-core is optional in loom-spring-boot. Applications that enable loomcache.session.enabled=true must also include Spring Session:

<dependency>
    <groupId>org.springframework.session</groupId>
    <artifactId>spring-session-core</artifactId>
</dependency>

Minimum configuration

Declare the profile, seed list, and client settings in application.yml:

loomcache:
  profile: development
  cluster:
    seeds:
      - 127.0.0.1:5701
  client:
    enabled: true
    connect-timeout-ms: 5000
    request-timeout-ms: 3000

Set loomcache.profile explicitly. Use development for local examples and production for production fail-closed identity, TLS, auth, persistence, session, and REST safety checks. Seed entries must point to LoomCache binary member ports. Do not use direct admin health ports (5702/5703) as seeds unless you explicitly reassigned those ports to member listeners.

Beans registered

When seeds are present and loomcache.client.enabled=true, LoomAutoConfiguration registers client-side beans. loomcache.client.enabled defaults to false, including in client-only apps, so applications opt in explicitly:

• LoomCache (bean name loomClient) — the synchronous client facade that wraps LoomClient; injected by type com.loomcache.client.LoomCache. Its close destroy method owns client shutdown.
• LoomCacheManager implementing org.springframework.cache.CacheManager — registered as @Primary when loomcache.spring-cache.enabled=true (the default). These caches are client-backed Loom maps; they do not use the optional JPA WriteThroughCacheStore for the embedded REST default map.
• LoomHealthIndicator (bean name loomcache) — picked up by Spring Boot actuator.

LoomSessionRepository is contributed by a separate LoomSessionAutoConfiguration (registered alongside LoomAutoConfiguration in AutoConfiguration.imports) and is created only when loomcache.session.enabled=true.

Embedded server beans are opt-in. Set loomcache.server.enabled=true to import the embedded server configuration; leaving it unset or false keeps the application in client-only mode.

Spring Cache abstraction

LoomCacheManager plugs into the standard Spring Cache annotations:

@Cacheable("products")
public Product findById(String id) { ... }

@CachePut("products")
public Product save(Product p) { ... }

@CacheEvict("products")
public void remove(String id) { ... }

Pre-create caches at startup:

loomcache:
  spring-cache:
    enabled: true
    cache-names: [products, users, orders]
    loader-lock-stripes: 256

Keep loomcache.spring-cache.default-ttl at 0. Non-zero values fail startup because Spring Cache putIfAbsent paths require an atomic put-if-absent-with-TTL operation that LoomMap does not expose yet. Cache names starting with loom: are reserved for internal LoomCache maps such as loom:sessions. loader-lock-stripes controls per-cache get(key, loader) lock striping; lower it when an application defines many cache names and does not need high same-cache loader concurrency.

Spring Session

Enable the session repository and session encryption in application.yml:

loomcache:
  session:
    enabled: true
    default-max-inactive-interval: 30m
    map-name: loom:sessions
    max-serialized-bytes: 1048576
    encryption:
      enabled: true
      secret: ${LOOMCACHE_SESSION_AES_KEY}

LoomSessionRepository implements SessionRepository<LoomSession>, storing each LoomSession as a Base64-encoded payload in the loom:sessions map, encrypting it with AES-GCM when loomcache.session.encryption.enabled=true, and rejecting serialized session payloads larger than max-serialized-bytes. The production profile refuses to start with loomcache.session.enabled=true unless loomcache.session.encryption.enabled=true. LOOMCACHE_SESSION_AES_KEY must contain a Base64-encoded non-zero 128, 192, or 256-bit AES key. Non-production deployments can disable encryption, but session payloads are then stored as plaintext and startup logs a warning.

Session attributes, Spring Cache JSON value types, and Java-serialized non-fast-path Spring Cache keys that contain application object types are deny-by-default. Built-in scalar values, java.time.* values, selected JDK collection containers, and Loom session infrastructure types are allowed without broad prefixes. Set loomcache.serialization.allowed-packages to the exact trusted package prefixes for application DTOs and Spring Cache enum/value classes that may cross this serialization boundary, and use loomcache.serialization.denied-types for specific classes that must remain blocked even inside allowed packages.

REST controllers

REST controllers are mounted under /api/* when their backing beans exist (see REST API). The query, map, queue, set, topic, cluster, multimap, list, ringbuffer, reliable-topic, transaction, and PN-counter (/api/counter) controllers require embedded-server beans from loomcache.server.enabled=true. /api/query also requires loomcache.client.enabled=true, which creates the smart-routing LoomCache bean, and query allow-listing must be configured for application predicates. The direct CP REST routes for /api/lock and /api/atomic are non-production controllers; they are not registered when loomcache.profile=production. In non-production they still fail closed with default write-safety settings unless explicitly enabled. Production CP access uses the binary protocol.

Inputs are validated through Bean Validation and the starter’s request guard; exceptions are translated into consistent Spring REST error responses.

Add org.springdoc:springdoc-openapi-starter-webmvc-api, then set loomcache.openapi.enabled=true and springdoc.api-docs.enabled=true to publish the generated LoomCache group for these controllers and /token at /v3/api-docs/loomcache-api; the LoomCache security chain keeps that endpoint admin-only unless a non-production deployment explicitly makes it public. Host applications that include SpringDoc may still expose their own default /v3/api-docs endpoint, so set springdoc.api-docs.enabled=false when no docs endpoint should exist. Direct LoomApplication launches keep Swagger UI disabled through the executable default springdoc.swagger-ui.enabled=false; dependency consumers should omit the optional UI dependency or set that key explicitly when UI tooling must stay off.

Actuator

LoomHealthIndicator reports the client’s connection status and a cluster health summary at /actuator/health/loomcache.

TLS & auth

server.ssl.* configures Spring Boot’s HTTPS REST listener. loomcache.tls.* maps to TlsConfig and protects the LoomCache binary listener. The Spring auth section exposes the embedded server gateway/role subset of AuthConfig; username, forwarded-roles, and certificate-auth are client credential properties for the auto-configured client and do not enable embedded server token, JAAS, LDAP, Kerberos, or certificate backends:

server:
  ssl:
    enabled: true
    key-store: ${LOOMCACHE_TLS_DIR}/keystore.p12
    key-store-password: ${SERVER_SSL_KEY_STORE_PASSWORD}
    trust-store: ${LOOMCACHE_TLS_DIR}/truststore.p12
    trust-store-password: ${SERVER_SSL_TRUST_STORE_PASSWORD}
    client-auth: need

loomcache:
  tls:
    enabled: true
    key-store-path: ${LOOMCACHE_TLS_DIR}/keystore.p12
    key-store-password: ${KEYSTORE_PASSWORD}
    trust-store-path: ${LOOMCACHE_TLS_DIR}/truststore.p12
    trust-store-password: ${TRUSTSTORE_PASSWORD}
    require-client-auth: true
    revocation-checking-enabled: true
    revocation-soft-fail: false
  auth:
    enabled: true
    gateway-trust: false
    cert-permissions:
      eu-west-prod-admin: ADMIN
      "eu-west-prod-client-*": READ_WRITE
    role-prefix: ROLE_
    roles:
      admin:
        permissions: ["*"]
      reader:
        permission-configs:
          - type: map
            instance: "*"
            actions: [read]

This production-shaped starter example uses Spring Boot server.ssl.* for HTTPS REST mTLS, loomcache.tls.* for the LoomCache binary listener, and client certificate CNs matching cert-permissions. Start the JVM with -Dcom.sun.net.ssl.checkRevocation=true plus CRLDP (-Dcom.sun.security.enableCRLDP=true) or OCSP so the REST mTLS preflight has a hard-fail revocation source. If management.server.port differs from server.port, configure management.server.ssl.* with the same HTTPS, client-auth, key, and trust material.

The Spring Boot binding surface exposes certificate credential selection, role definitions, forwarded gateway trust, and certificate permission maps; production rejects forwarded gateway trust, so configure certificate permissions for Spring production authorization. Token and JAAS/LDAP/Kerberos server auth backends require direct AuthConfig or direct properties/YAML configuration.

Optional Spring Security JWT issuing:

loomcache:
  security:
    jwt:
      enabled: true
      signing-secret: ${LOOMCACHE_JWT_SIGNING_SECRET}
      ttl: 15m
      local-revocation-enabled: false

Use a high-entropy, non-placeholder UTF-8 signing secret of at least 32 bytes; generate deployment values with openssl rand -base64 32. Rotation entries under loomcache.security.jwt.verification-secrets must meet the same strength requirement.

When enabled, a caller authenticated by mTLS/X.509 client certificate with the token-issuer authority and the ADMIN or USER role can POST /token to receive a short-lived HS256 Bearer token (default ttl 15m, minimum 60s); the issued token is bound to the presenting certificate. Production JWT deployments keep loomcache.security.jwt.local-revocation-enabled=false; use short token TTLs, signing-key rotation, or configured deny-list entries for emergency revocation. Bearer tokens themselves cannot mint new tokens.

/token is not under /api/

The token endpoint is mapped to /token, not /api/token. It sits outside the REST API prefix, so ensure your reverse proxy, firewall rules, and rate-limiting configuration cover this path explicitly.

Tests

For application tests, cover the integration points your service actually enables:

• Configuration binding: seed addresses, TLS/auth settings, cache/session options, and whether loomcache.server.enabled should start an embedded node.
• Bean availability: the LoomCache facade, optional LoomCacheManager, session repository, and Actuator health indicator in the profiles where your application expects them.
• HTTP surfaces: /actuator/health/loomcache, /v3/api-docs/loomcache-api when OpenAPI is explicitly enabled, /token when JWT issuing is enabled, and the /api/* endpoints your service exposes.
• Production posture: TLS/mTLS, certificate permissions, persistence directories, and fail-closed behavior for unsupported external-store adapters.

For embedded-server deployments, add a staging smoke test with the same seed list, ports, persistence path, and security profile you plan to run in production.