Class LoomClient.Builder

java.lang.Object
com.loomcache.client.LoomClient.Builder
Enclosing class:
LoomClient
public static final class LoomClient.Builder extends Object

  • Constructor Details

    • Builder

      public Builder()

  • Method Details

    • addSeed

      public LoomClient.Builder addSeed(String address)
      Add a seed address to the cluster. Accepts IPv4 host:port, hostname host:port, and bracketed IPv6 [::1]:port.

    • seeds

      public LoomClient.Builder seeds(List<String> addresses)
      Add multiple seed addresses to the cluster. Each address is validated via addSeed(String).

    • seeds

      public LoomClient.Builder seeds(String... addresses)
      Add multiple seed addresses to the cluster. Each address is validated via addSeed(String).

    • connectionTimeout

      public LoomClient.Builder connectionTimeout(Duration d)
      Set connection timeout.

    • requestTimeout

      public LoomClient.Builder requestTimeout(Duration d)
      Set request timeout.

    • maxRetries

      public LoomClient.Builder maxRetries(int n)
      Set max retry attempts for failed requests.

    • retryBaseDelay

      public LoomClient.Builder retryBaseDelay(Duration d)
      Set base delay between retries.

    • maxInFlightRequests

      public LoomClient.Builder maxInFlightRequests(int max)
      Set the maximum number of client requests tracked as in-flight.

    • routingMode

      public LoomClient.Builder routingMode(ClientRoutingMode mode)
      Set cluster routing mode. Defaults to ClientRoutingMode.ALL_MEMBERS.

    • routingMemberGroup

      public LoomClient.Builder routingMemberGroup(String memberGroup)
      Select the configured member group used by ClientRoutingMode.MULTI_MEMBER.

    • routingPartitionGroupConfig

      public LoomClient.Builder routingPartitionGroupConfig(PartitionGroupConfig config)
      Set the IP/CIDR member-group definitions used by ClientRoutingMode.MULTI_MEMBER.

    • asyncStart

      public LoomClient.Builder asyncStart(boolean on)
      Enable asynchronous startup. When enabled, build() clients return from LoomClient.connect() immediately and establish the first connection in the background.

    • reconnectMode

      public LoomClient.Builder reconnectMode(ClientReconnectMode mode)
      Set reconnect behavior after the last member connection is lost.

    • tlsConfig

      public LoomClient.Builder tlsConfig(TlsConfig config)
      Set TLS configuration for secure connections.

    • auth

      public LoomClient.Builder auth(String username, String roles)
      Configure gateway-forwarded auth credentials. The gateway validates JWT and forwards user identity + roles.
      Parameters:
      username - the authenticated username (from gateway's X-Auth-User)
      roles - comma-separated roles (from gateway's X-Auth-Roles), or password for direct JAAS auth

    • credentialsFactory

      public LoomClient.Builder credentialsFactory(CredentialsFactory factory)
      Configure a credentials factory for AUTH handshakes.

      The factory is invoked for each node connection that needs credentials, including reconnects and leader redirects. If both auth(String, String) and a factory are configured, the factory takes precedence.

    • nearCacheEnabled

      public LoomClient.Builder nearCacheEnabled(boolean on)
      Enable or disable the local near cache.

    • nearCacheTtl

      public LoomClient.Builder nearCacheTtl(Duration d)
      Set near cache time-to-live.

    • nearCacheMaxSize

      public LoomClient.Builder nearCacheMaxSize(int max)
      Set near cache max entries.

    • nearCacheEvictionPolicy

      public LoomClient.Builder nearCacheEvictionPolicy(NearCacheEvictionPolicy policy)
      Set the capacity eviction policy for the near cache. Defaults to NearCacheEvictionPolicy.LRU.

    • nearCacheLocalUpdatePolicy

      public LoomClient.Builder nearCacheLocalUpdatePolicy(NearCacheLocalUpdatePolicy policy)
      Set how local writes update the near cache. Defaults to NearCacheLocalUpdatePolicy.INVALIDATE.

    • nearCachePreloaderConfig

      public LoomClient.Builder nearCachePreloaderConfig(NearCachePreloaderConfig config)
      Set keys-only near-cache preloader persistence. Disabled by default.

    • nearCacheReconciliationConfig

      public LoomClient.Builder nearCacheReconciliationConfig(NearCacheReconciliationConfig config)
      Set periodic near-cache anti-entropy reconciliation. Enabled by default.

    • clientStatisticsConfig

      public LoomClient.Builder clientStatisticsConfig(ClientStatisticsConfig config)
      Set periodic client statistics upload configuration. Disabled by default.

    • clientStatisticsEnabled

      public LoomClient.Builder clientStatisticsEnabled(boolean enabled)
      Enable or disable periodic client statistics uploads.

    • clientStatisticsUploadInterval

      public LoomClient.Builder clientStatisticsUploadInterval(Duration interval)
      Set the interval for periodic client statistics uploads.

    • nearCacheSerializeKeys

      public LoomClient.Builder nearCacheSerializeKeys(boolean serializeKeys)
      Store near-cache keys using their serialized byte form. Disabled by default.

    • strictHandshake

      public LoomClient.Builder strictHandshake(boolean on)
      Opt into strict protocol-version handshake (BLK-2026-04-22-007 Day 1, Session 7 Sub-mission 2a). When enabled, a PROTOCOL_HELLO + PROTOCOL_HELLO_ACK exchange runs on each new connection before any request is sent. Peers whose version is incompatible per the static ProtocolNegotiator.COMPATIBILITY_MATRIX cause the connection to be closed with an IOException so the client can move on to the next seed.

      Default: false (v2.0 behaviour — no handshake). Callers deploying a rolling-upgrade window across v2.x minors should set this to true so mixed-version clusters surface version drift immediately instead of failing later at first incompatible op.

      Session 8 ESC-1: the flag is now wired through to ConnectionManager.createConfiguredSocket which invokes ProtocolHandshake.performHandshake(java.net.Socket, java.util.EnumSet) on every newly-opened socket before the reader thread is started. Compatible peers transparently continue; incompatible peers cause the connect attempt to fail with an IOException and the client falls through to the next seed via its existing retry loop.

      Parameters:
      on - whether to enable strict handshake
      Returns:
      this builder

    • registerClass

      public LoomClient.Builder registerClass(Class<?> clazz, int id)
      Register an application class with the client Kryo serializer.

      The same class and ID must be registered on every server node that may deserialize this payload.

    • registerClass

      public <T> LoomClient.Builder registerClass(Class<T> clazz, int id, com.esotericsoftware.kryo.Serializer<? super T> serializer)
      Register an application class with a class-specific Kryo serializer.

      The class-specific serializer is resolved before Kryo's default class serializer. The same class, ID, and serializer must be registered on every server node that may deserialize this payload.

    • build

      public LoomClient build()