Configuration Reference

This page is the reference for LoomCache runtime configuration. Configuration flows through immutable classes, including ClusterConfig, TlsConfig, EndpointTlsConfig, and AuthConfig, plus the Spring Boot loomcache.* binding declared in LoomProperties.

Configuration Sources

45+ properties across a dozen-plus groups. Three ways to configure.

Builder APIapplication.ymlEnvironment

J

Builder API

ClusterConfig.builder()

.nodeId("node-1")

.port(5701)

.heartbeatTimeoutMs(60000)

.dataDir("./data")

.build();

Categories

Identity3

Raft8

Network10

Persistence4

Security11

Observability7

The node1, node2, and node3 Spring profiles used by scripts/start-cluster.sh live under config/local-cluster, not in packaged Spring Boot application resources. They are local-development profiles loaded with spring.config.additional-location; production node profiles must come from deployment-specific external configuration.

Runtime profile

Set loomcache.profile=production or LOOMCACHE_PROFILE=production for production fail-closed identity, TLS, auth, persistence, sharding, session, and REST safety checks. prod is accepted as an alias. Use development or dev only for local development; production evidence and deployment examples must set the production profile explicitly.

ClusterConfig

Property	Type	Default	Notes
clusterId	String	dev	Development default only. Production requires an explicit stable cluster ID; nodes with different IDs ignore each other’s JOIN.
nodeId	String	node-1	Development default only. Production requires an explicit stable per-node identity.
host	String	127.0.0.1	Advertised/routable node host. Use bindAddress for the listener bind address.
bindAddress	String	host	Local listener bind address. Use 0.0.0.0 to bind all interfaces, but never advertise it to peers.
port	int	5701	1–65535.
instanceNumber	int	1	≥ 0.
seeds	List	[]	host:port bootstrap peers.
heartbeatIntervalMs	long	5000	≥ 100.
heartbeatTimeoutMs	long	60000	Must exceed heartbeatIntervalMs.
maxMemoryBytes	long	1 GiB	Eviction trigger for the data-structure registry.
maxExecutorTaskPayloadBytes	int	1_048_576	Maximum serialized Callable payload accepted by executor submit operations.
readBackupData	boolean	false	Non-production embedded/member-local compatibility option. When true, local reads may use backup data instead of read-index and values can be stale; production startup rejects it.
transactionMaxBufferedOps	int	10_000	Maximum operations buffered in one transaction context.
transactionMaxParticipantGroupCount	int	4_096	Maximum participant Raft groups accepted by one cross-group 2PC transaction.
transactionMaxOperationPayloadBytes	int	16_777_216	Maximum serialized per-operation 2PC payload.
transactionCommitApplyRetryDelayMs	long	500	Delay between participant commit-apply retry attempts.
transactionCommitApplyMaxAttempts	int	20	Maximum participant commit-apply attempts before surfacing a commit-apply failure.
tlsConfig	TlsConfig	TlsConfig.disabled()	See below.
endpointTlsConfig	EndpointTlsConfig	EndpointTlsConfig.disabled()	Member, client, and WAN endpoint TLS roles.
authConfig	AuthConfig	AuthConfig.disabled()	See below.
dataDir	String	null	Development/test default only. null disables WAL + snapshots; production requires persistence, an explicit durable data/WAL directory, and storage that honors WAL fsync.
idGeneratorNodeId	int	derived from nodeId	Snowflake-style ID generator node id. Direct properties use loomcache.id-generator.node-id; Spring Boot uses loomcache.node.id-generator-node-id.
idempotencyTtlMs	long	900_000	TTL for idempotency dedup cache; aligned with 2PC decision retention.
queueConfigs	Map	{}	Per-queue capacity/max-size and empty-queue TTL declarations.
priorityQueueConfigs	Map	{}	Per-priority-queue comparator class declarations.

TlsConfig

Property	Default	Notes
enabled	false	TLS switch; production requires this to be set explicitly to true.
keyStorePath	null	PKCS12 / JKS, or a provider-supported type.
keyStorePassword	""	Masked in toString().
keyStoreType	PKCS12
trustStorePath	null
trustStorePassword	""
trustStoreType	PKCS12
requireClientAuth	false (omitted values resolve to true in production once TLS is enabled)	mTLS switch.
protocols	["TLSv1.3", "TLSv1.2"]
cipherSuites	[]	Empty → curated safe default suites.
provider	JDK	Use JDK for the shipped blocking client/server socket transports. OPENSSL and OPENSSL_REFCNT are supported only when the application supplies explicit Netty native TLS runtime dependencies. FIPS-controlled deployments should use JDK with a validated JSSE provider.
certExpirationWarningDays	30	Configuration threshold for external certificate-expiration tracking; LoomCache does not emit a runtime warning or gauge for it.
certExpirationCriticalDays	7	Critical threshold — alerting territory.
revocationCheckingEnabled	false (omitted values resolve to true in production once TLS is enabled)	Enable CRL/OCSP.
revocationSoftFail	true (omitted values resolve to false in production once TLS is enabled)	Production requires hard-fail revocation.
acceptTimeoutMs	2000	Server-socket SO_TIMEOUT.

The current binary listener initializes its SSLContext at startup. Treat production certificate rotation as a rolling restart.

EndpointTlsConfig

EndpointTlsConfig lets one node carry separate TLS settings for member-to-member, member-to-client, and WAN roles:

EndpointTlsConfig endpointTls = EndpointTlsConfig.builder()
    .defaults(tls)
    .memberTlsConfig(memberTls)
    .clientTlsConfig(clientTls)
    .wanTlsConfig(wanTls)
    .build();

The tlsConfig setter applies one TlsConfig to every endpoint. When endpoint TLS is supplied explicitly, the tlsConfig() accessor exposes the member endpoint config. The current binary TCP listener is still a single socket and consumes the member endpoint config at runtime. Direct production startup rejects distinct client/WAN endpoint TLS settings until dedicated inbound listeners exist; use identical endpoint settings for a single-process node, or terminate/split listeners outside the process.

AuthConfig

Property	Default	Notes
enabled	false
gatewayTrust	false	Trust forwarded headers from an API gateway. This is opt-in; when auth is enabled without gateway trust, cert permissions, JAAS, LDAP, Kerberos, or token config, startup fails closed. Production profiles reject gatewayTrust=true.
rolePrefix	ROLE_	Prefix stripped from role names.
roleSeparator	,
trustedGatewayAddresses	{}	Only trust gateway headers from these source addresses. The properties loader supplies loopback defaults (127.0.0.1, ::1, 0:0:0:0:0:0:0:1, localhost) only when gatewayTrust=true is explicitly configured and this property is omitted.
roles	{}	Role → permission set.
certPermissions	{}	mTLS certificate CN exact match or prefix pattern ending in * → permission level. Regex and bare * are rejected.

Certificate common-name permissions use longest-match resolution, so the longest exact or terminal-* prefix match wins. See Security & mTLS for examples of both authorization styles.

Spring Boot (loomcache.*)

The Spring Boot starter binds the following loomcache.* property groups through LoomProperties:

loomcache.cluster

• seeds: list of host:port.
• node-id, cluster-id: optional for development; omitted values use the development defaults (node-1 and dev). Production must set an explicit stable cluster identity and a unique stable node identity for every member.

loomcache.node

• id (node-1), host (127.0.0.1), port (5701), instance (1). host is the advertised member host, not a bind-all address. Use loomcache.server.bind-address for the local listener interface. See Default Ports for how this binary member port relates to the Docker sample port 7654.
• id-generator-node-id: Spring Boot binding for ClusterConfig.idGeneratorNodeId. Direct loomcache.properties uses loomcache.id-generator.node-id; direct YAML may use either loomcache.node.id-generator-node-id or loomcache.id-generator.node-id.

loomcache.client

• connect-timeout-ms (5000), request-timeout-ms (120000), max-retries (3).
• async-start (false): returns from client startup before the first member connection is established; operations fail fast until the initial connection succeeds.
• reconnect-mode (ON / ASYNC / OFF): ON retries in the background while invocations wait up to their timeout, ASYNC retries but fails invocations fast while reconnecting, and OFF closes the client on last-connection loss.
• routing-mode (ALL_MEMBERS / SINGLE_MEMBER / MULTI_MEMBER): smart routing opens member connections across the cluster; single-member routing keeps one unisocket-style member connection; multi-member routing filters seed connections to a configured member group.
• routing-member-group and routing-member-groups[].interfaces: selected member group and IP/CIDR ranges for MULTI_MEMBER client routing.
• near-cache.enabled (false; LoomClient.Builder also defaults to false), near-cache.max-size (10000), near-cache.ttl-seconds (0, meaning no TTL), near-cache.eviction-policy (LRU, LFU), near-cache.local-update-policy (INVALIDATE, CACHE_ON_UPDATE), near-cache.serialize-keys (false), near-cache.poll-default-interval-seconds (30; base polling interval for server-side invalidation events), near-cache.poll-min-interval-seconds (1; minimum back-off floor for the adaptive invalidation poll). Near-cache LRU/LFU is client-local freshness/capacity policy, not server-side data-retention or Hazelcast max-idle parity.
• near-cache.preloader.enabled (false), near-cache.preloader.directory (loomcache-near-cache-preloader), near-cache.preloader.store-initial-delay-seconds (600), and near-cache.preloader.store-interval-seconds (600) persist keys only for restart warmup.
• near-cache.reconciliation.enabled (true), near-cache.reconciliation.interval-seconds (60), and near-cache.reconciliation.tolerated-miss-count (10) periodically compare server invalidation sequences and clear a map when too many invalidations were missed.
• statistics.enabled (false) and statistics.upload-interval-seconds (3) enable best-effort periodic upload of client JVM/process, connection, and near-cache counters to a connected member.

loomcache.server

• enabled (false), bind-address (127.0.0.1). The embedded node binds with loomcache.node.port.
• Deprecated compatibility property: port (5701). Do not use it for new deployments; set loomcache.node.port instead. loomcache.server.port is ignored for embedded-node binding and logs a warning when it differs from loomcache.node.port.
• raft.election-timeout-ms (60000), raft.heartbeat-interval-ms (5000): despite the raft prefix, these map to ClusterConfig heartbeat timeout/interval for cluster heartbeat and failure detection.
• health.icmp.* controls the optional ICMP/TCP-echo layer for failure detection: enabled, timeout-ms, interval-ms, max-attempts, and fail-fast-on-startup.
• diagnostics.slow-operation.* controls the slow operation detector, which defaults to enabled: enabled, threshold-ms, sample-interval-ms, max-records, and max-stack-frames.
• persistence.enabled (false; development/test default only), persistence.wal-directory (persistence), persistence.snapshot-threshold (10000). Production must enable persistence, set an explicit durable data/WAL directory, and run on storage where WAL fsync is honored.
• migration.max-parallel-migrations (10) caps concurrent partition migrations per node.
• migration.durable-chunks (false) enables the durable migration chunk path used by sharding validation. It is required for a production migration release but does not by itself enable production ownership cutover.
• wan.durable-outbound (false) makes outbound WAN publisher events Raft/WAL-durable before send. Production WAN target registration remains fail-closed unless this is enabled.
• executor.max-task-payload-bytes (1048576) caps serialized Callable payloads for executor submit operations.
• read-backup-data (false) serves member-local reads from local backup data instead of read-index; enable only for non-production embedded/member-local compatibility workloads that can tolerate stale reads. The production profile rejects this setting and keeps reads on the linearizable path.
• partition-group.type (PER_MEMBER / HOST_AWARE / PLACEMENT_AWARE / CUSTOM / SPI) controls primary/backup placement failure domains; PLACEMENT_AWARE expects member attributes such as zone, placement-group, and placement-partition, CUSTOM uses configured CIDR/IP member groups, and SPI uses discovery-provided partition-group member attributes.
• eviction.policy (NONE / LRU / LFU / FIFO / RANDOM), eviction.max-entries (default 0 meaning unbounded, across all profiles), eviction.max-memory-bytes (Java-code default 1073741824 = 1 GiB; the production Docker template overrides this to 9223372036854775807 = Long.MAX_VALUE to disable memory-based eviction). Production profiles must use NONE, 0, and Long.MAX_VALUE; server-side LRU/LFU/FIFO/RANDOM, finite max-entry/max-memory eviction, and max-idle remain unsupported until eviction decisions are Raft-applied and proven through WAL/snapshot/restart tests.
• hot-key.* — accepted and validated, but the feature is not yet wired; non-default values log a warning in development and fail startup in production.

loomcache.queues

Declarative queue configs are keyed by queue name. capacity and max-size are aliases; 0 means unbounded. empty-queue-ttl-millis is milliseconds, and -1 disables empty queue removal.

loomcache:
  queues:
    jobs:
      capacity: 256
      empty-queue-ttl-millis: 30000
    audit:
      max-size: 64
      empty-queue-ttl-millis: 1500

Equivalent properties:

loomcache.queues.jobs.capacity=256
loomcache.queues.jobs.empty-queue-ttl-millis=30000
loomcache.queues.audit.max-size=64
loomcache.queues.audit.empty-queue-ttl-millis=1500

Spring Boot uses the same top-level binding: loomcache.queues.<queue-name>.*.

loomcache.priority-queues

Declarative priority queue configs are keyed by queue name. priority-comparator-class-name is the fully qualified name of a class on the server classpath that implements the deterministic priority-queue comparator marker interface. A class implementing only java.util.Comparator<String> is rejected. Lower numeric priority still wins first; the comparator orders items that share the same numeric priority.

loomcache:
  priority-queues:
    critical:
      priority-comparator-class-name: com.example.CriticalComparator

Equivalent properties:

loomcache.priority-queues.critical.priority-comparator-class-name=com.example.CriticalComparator
loomcache.priority-queues.audit.priority-comparator-class-name=com.example.AuditComparator

Spring Boot uses the same top-level binding: loomcache.priority-queues.<queue-name>.priority-comparator-class-name.

loomcache.tls

• enabled, key-store-path, key-store-password (JSON-ignored), key-store-type, trust-store-path, trust-store-password, trust-store-type, require-client-auth, protocols, provider, revocation-checking-enabled (false; enable CRL/OCSP revocation checks), revocation-soft-fail (true; when false, startup aborts if the CRL/OCSP endpoint is unreachable).
• Spring Boot property binding does not currently expose cipherSuites; use direct TlsConfig customization or provider-level disabled algorithms when a deployment must pin an explicit cipher allowlist.
• Endpoint overrides inherit the global loomcache.tls.* settings unless set: member.*, client.*, and wan.* each support enabled, key-store-path, key-store-password, key-store-type, trust-store-path, trust-store-password, trust-store-type, require-client-auth, protocols, provider, revocation-checking-enabled, and revocation-soft-fail.

Note

Programmatic TlsConfig.builder() does not enable TLS by itself. Direct properties/YAML loaders and Spring Boot binding also require loomcache.tls.enabled=true explicitly. Once TLS is enabled, omitted mTLS/revocation booleans resolve to production-safe values under the production profile: require-client-auth=true, revocation-checking-enabled=true, and revocation-soft-fail=false. Production startup rejects missing TLS, disabled mTLS, disabled revocation checking, soft-fail revocation, or missing trust/key material instead of silently accepting insecure values.

loomcache.auth

• Server auth binding: enabled, gateway-trust, role-prefix, role-separator, trusted-gateway-addresses (list of CIDRs/IPs that may supply forwarded-role headers; loopback addresses are added automatically when gateway-trust=true and this list is omitted), max-sessions (100000), roles.<name>.permissions, roles.<name>.permission-configs[].type, roles.<name>.permission-configs[].instance, roles.<name>.permission-configs[].actions, and cert-permissions.<cn-pattern> (permission level keyed by exact certificate CN or a non-empty prefix ending in *; regex and bare * are rejected).

Spring Boot binding covers this gateway/role/certificate surface; token and JAAS/LDAP/Kerberos server auth backends require direct AuthConfig or direct properties/YAML configuration. The username, forwarded-roles, and certificate-auth Spring properties feed only the auto-configured client credentials; embedded server auth ignores them, and production client validation rejects forwarded role credentials as insufficient.

Spring REST security surfaces

• loomcache.security.jwt.* controls the REST JWT issuer/verifier: enabled (false), signing-secret (high-entropy, non-placeholder UTF-8 secret, at least 32 bytes when enabled; generate with openssl rand -base64 32), key-id (default; must not be reused by rotated verification secrets), verification-secrets (retired key ids with the same secret strength), issuer (loomcache-rest), audience (loomcache-rest-api), ttl (15m, minimum 60s and greater than allowed-clock-skew), allowed-clock-skew (30s, maximum 5m and lower than ttl), revoked-token-ids, local-revocation-enabled (true; production rejects local runtime revocation), and max-revoked-token-ids (100000).
• loomcache.security.rate-limit.* applies REST token buckets: authenticated capacity (1000) and refill-per-second (200), anonymous anonymous-capacity (60) and anonymous-refill-per-second (20), trusted-proxies, and max-buckets (100000).
• loomcache.security.user-lockout.* covers REST authentication lockout: enabled (true), consecutive-fail-count (5), lockout-duration (5m), per-ip-failure-limit (20), per-ip-window (1m), and trusted-proxies.
• loomcache.security.cors.* controls REST CORS: enabled (false), allowed-origins, allowed-origin-patterns, allowed-methods, allowed-headers, exposed-headers, allow-credentials (false), and max-age (1h).
• loomcache.security.public-endpoints.openapi-docs and loomcache.security.public-endpoints.actuator-info default to admin-only; non-production can opt in explicitly, and production rejects true.
• loomcache.openapi.enabled (false) registers SpringDoc/OpenAPI beans for /v3/api-docs/** only when explicitly enabled and org.springdoc:springdoc-openapi-starter-webmvc-api is on the application classpath.
• loomcache.rest.write-safety.* defaults direct-reads-enabled, direct-writes-enabled, and operator-admin-mutations-enabled to false; production refuses to start when any of them are true.
• Spring REST production TLS is separate from loomcache.tls.*, which protects the LoomCache binary listener. Set server.ssl.enabled=true, server.ssl.client-auth=NEED, server key material (server.ssl.key-store or server.ssl.certificate plus server.ssl.certificate-private-key), and trust material (server.ssl.trust-store or server.ssl.trust-certificate). If management.server.port differs from server.port, configure the same HTTPS and mTLS requirements under management.server.ssl.*. Production REST startup also requires hard-fail JSSE revocation: -Dcom.sun.net.ssl.checkRevocation=true plus CRLDP (-Dcom.sun.security.enableCRLDP=true) or OCSP.

loomcache.spring-cache

• enabled (true), cache-names (list of pre-created names).
• default-ttl must remain 0 until LoomMap exposes atomic put-if-absent-with-TTL semantics; non-zero values fail startup.
• loader-lock-stripes (256) controls per-cache striped locks used by Spring Cache get(key, loader) calls; lower it for applications with many cache names and low loader concurrency.
• Cache names starting with loom: are reserved for internal maps such as loom:sessions.

loomcache.session

• enabled (false), default-max-inactive-interval (30m), map-name (loom:sessions).
• max-serialized-bytes (1_048_576) bounds one serialized Java session payload before storage or deserialization. The loom: prefix is reserved for internal LoomCache maps.
• encryption.enabled (false), encryption.secret (JSON-ignored): when enabled, session payload bytes are encrypted at rest using the configured secret before storage in loom:sessions. The production profile requires loomcache.session.encryption.enabled=true when loomcache.session.enabled=true; encryption.secret must be a Base64-encoded non-zero 128, 192, or 256-bit AES key supplied from a secret manager or environment variable.

loomcache.serialization

• allowed-packages lists trusted application package prefixes for Spring Session Java serialization, Spring Cache JSON value type resolution, and Java-serialized non-fast-path Spring Cache keys.
• denied-types lists fully qualified class names that are always rejected, even if their package is allowed.
• Built-in scalar values, java.time.*, selected JDK collection containers, and Loom session payloads are allowed without adding broad java.* or com.loomcache.* package prefixes. Application DTOs and Spring Cache enum/value classes should be added with exact trusted package prefixes.

loomcache.network

These keys provide low-level TCP tuning for direct node properties and the Spring Boot LoomProperties binding. In Spring Boot embedded deployments they map into the embedded node’s cluster configuration.

Key	Default	Notes
loomcache.network.max-connections	10000	Maximum number of concurrent client connections the node accepts.
loomcache.network.read-timeout-ms	30000	Read timeout applied to client connections.
loomcache.network.idle-timeout-ms	300000	Idle timeout after which an inactive client connection is closed.
loomcache.network.tcp-accept-timeout-ms	2000	SO_TIMEOUT on the server-socket accept loop.
loomcache.network.tcp-accept-backoff-max-ms	5000	Maximum back-off delay before retrying accept() after a burst of connection errors.
loomcache.network.tcp-write-queue-capacity	1024	Per-connection outbound message queue depth. Writes that exceed this cap are rejected with a send error.
loomcache.network.shutdown-drain-ms	30000	Time to allow in-flight requests to complete before the TCP listener closes during graceful shutdown. Docker sets LOOMCACHE_NETWORK_SHUTDOWN_DRAIN_MS=60000.

loomcache.query

Key	Default	Notes
loomcache.query.max-aggregate-scan-entries	1000000	Maximum map entries scanned per aggregation query.
loomcache.query.max-sql-length	1000000	Maximum SQL statement length in characters.
loomcache.query.max-regex-input-length	65536	Maximum string length passed to a SQL regex predicate.
loomcache.query.slow-query-threshold-ms	100	Queries exceeding this duration are logged and metered.
loomcache.query.timeout-ms	30000	Hard query timeout; the coordinator aborts and returns an error.
loomcache.query.allowed-maps	[]	When non-empty, SQL queries are restricted to these map names.

loomcache.batch

Key	Default	Notes
loomcache.batch.raft-submit-timeout-ms	10000	Timeout for submitting a committed atomic batch to the Raft log.

loomcache.idempotency

Key	Default	Notes
loomcache.idempotency.ttl-ms	900000	TTL for the idempotency dedup cache; aligned with 2PC decision retention.
loomcache.idempotency.batch-replay-cache-entries	65536	In-memory LRU size for detecting duplicate batch submissions.
loomcache.idempotency.data-write-replay-cache-entries	65536	In-memory LRU size for detecting duplicate single-key write replays.

loomcache.transactions

Key	Default	Notes
loomcache.transactions.max-buffered-ops	10000	Maximum operations buffered in a single transaction before commit.
loomcache.transactions.max-participant-group-count	4096	Maximum number of Raft groups that can participate in one cross-group 2PC transaction.
loomcache.transactions.max-operation-payload-bytes	16777216 (16 MiB)	Maximum serialized payload for a single transactional operation.
loomcache.transactions.commit-apply-retry-delay-ms	500	Delay between 2PC participant commit-apply retry attempts.
loomcache.transactions.commit-apply-max-attempts	20	Maximum 2PC participant commit-apply attempts before surfacing a commit apply failure.

loomcache.shutdown

Key	Default	Notes
loomcache.shutdown.max-wait-seconds	600	Total time allowed for a graceful shutdown sequence to complete.
loomcache.shutdown.hook.enabled	true	Register a JVM shutdown hook that initiates graceful shutdown on SIGTERM.
loomcache.shutdown.hook.policy	GRACEFUL	GRACEFUL drains in-flight requests; TERMINATE skips the graceful drain.

loomcache.admin

Key	Default	Notes
loomcache.admin.enabled	true	Enable the embedded direct admin listener. Docker and Spring Boot production templates set this to false and use Actuator instead. In production, enabling direct admin requires TLS-only mTLS health.
loomcache.admin.port	5702	Port for the direct-node admin HTTP listener when plaintext is allowed. Production with direct admin must set loomcache.server.health.tls.enabled=true, plain-text-disabled=true, and use the TLS listener on 5703 or an override.

ID generator node id

Key	Default	Notes
loomcache.node.id-generator-node-id	derived from nodeId hash	Spring Boot key for the Snowflake-style distributed ID generator node id.
loomcache.id-generator.node-id	derived from nodeId hash	Direct loomcache.properties key for standalone/server config loaders.

Set this value explicitly in production to guarantee uniqueness across nodes that share a common nodeId prefix.

loomcache.server.raft.bootstrap-servers

This property lists the nodeId=host:port entries that form the initial Raft voter set. Every static voter must appear here, and the list must be identical across all bootstrap members. The Raft group is bootstrapped only once; subsequent restarts use the persisted membership log.

loomcache:
  server:
    raft:
      bootstrap-servers:
        - loomcache-1=loomcache-1.eu-west.prod.lan:7654
        - loomcache-2=loomcache-2.eu-west.prod.lan:7654
        - loomcache-3=loomcache-3.eu-west.prod.lan:7654

Equivalent environment variables:

LOOMCACHE_SERVER_RAFT_BOOTSTRAP_SERVERS=loomcache-1=loomcache-1.eu-west.prod.lan:7654,loomcache-2=loomcache-2.eu-west.prod.lan:7654,loomcache-3=loomcache-3.eu-west.prod.lan:7654

loomcache.server.sharding

Key	Default	Notes
loomcache.server.sharding.enabled	false	Enable multi-group sharding. Production deployments must leave this false; see the production support boundaries in Docker & Deployment.
loomcache.server.sharding.num-groups	1	Number of Raft partition groups when sharding is enabled.

loomcache.data-connections and generic JDBC MapStore

loomcache.data-connections declares named JDBC connection pools. Each named entry maps to a DataConnectionConfig and can be referenced by map-store definitions. The following example declares a pooled Oracle connection and a map store that references it:

loomcache:
  data-connections:
    primary:
      jdbc-url: "jdbc:oracle:thin:@oracle.eu-west.cert.lan:1521/LOOMCACHE"
      driver-class-name: oracle.jdbc.OracleDriver
      username: loomcache
      password: "${DB_PASSWORD}"
      max-pool-size: 10
      pool-acquire-timeout-millis: 5000
  maps:
    orders:
      map-store:
        enabled: true
        data-connection-ref: primary
        table-name: LOOMCACHE_MAP
        key-column: MAP_KEY
        value-column: MAP_VALUE
        write-through: true   # development/validation only; production profiles reject it
        write-behind: false
        write-batch-size: 100
        load-mode: LAZY       # development/validation only; production profiles reject lazy read-through

The GenericMapStore upserts via Oracle MERGE INTO syntax. The Postgres INSERT ... ON CONFLICT form is not supported and is rejected by the release-hardening gate. Packaged generic JDBC MapStore declarations are disabled in production profiles; custom MapStore implementations require clustered server leader-owned writes, Raft-backed snapshot/graceful-drain recovery for write-behind queues, and the leader-owned read-through fill path before production use.

Client builder (non-Spring)

Common methods on LoomClient.Builder:

• addSeed(String) / seeds(List|String...)
• connectionTimeout(Duration) / requestTimeout(Duration) / retryBaseDelay(Duration)
• maxRetries(int)
• batchMaxOperations(int) (1..the supported release limit)
• asyncStart(boolean) / reconnectMode(ClientReconnectMode)
• tlsConfig(TlsConfig)
• credentialsFactory(CredentialsFactory) for production certificate/token credentials
• auth(String user, String rolesCsv) for non-production forwarded AUTH roles
• nearCacheEnabled(boolean) / nearCacheTtl(Duration) / nearCacheMaxSize(int) / nearCacheEvictionPolicy(NearCacheEvictionPolicy) / nearCacheLocalUpdatePolicy(NearCacheLocalUpdatePolicy) / nearCachePreloaderConfig(NearCachePreloaderConfig) / nearCacheReconciliationConfig(NearCacheReconciliationConfig) / nearCacheSerializeKeys(boolean)
• clientStatisticsConfig(ClientStatisticsConfig) / clientStatisticsEnabled(boolean) / clientStatisticsUploadInterval(Duration)

Client async helpers:

• Pipelining.withDepth(int) or AsyncLoomClient.pipelining(int) creates a bounded in-flight helper for CompletionStage operations; add(stage) blocks at capacity and results() returns values in add order.

Client blue/green failover:

• ClientConfig.builder() captures one cluster’s seeds, timeouts, TLS, near-cache, routing, async-start, and reconnect settings.
• ClientFailoverConfig.builder().client(...).tryCount(n) orders multiple client configs and limits rollover attempts.
• FailoverLoomClient.connect(config) connects to the first reachable config; failover() closes the active client before rolling to the next reachable config. LoomCache.connectFailover(config) provides the same startup behavior for the convenience wrapper.

Client listeners:

• addLifecycleListener(LifecycleListener) observes client start, shutdown, member connection, and member disconnect states; FailoverLoomClient also emits CLIENT_CHANGED_CLUSTER after a successful blue/green rollover.
• addMembershipListener(MembershipListener) observes member add/remove events; InitialMembershipListener also receives the current member snapshot at registration.
• addDistributedObjectListener(DistributedObjectListener) observes unique client proxy creation for maps, queues, topics, CRDTs, counters, and other distributed-object handles.

For listener and sample port allocation, see Default Ports. For production templates that apply these properties, see Docker & Deployment.