Class ClientPartitionTable

java.lang.Object
com.loomcache.client.ClientPartitionTable
public final class ClientPartitionTable extends Object
Client-side cache of the server's partition-to-group ownership snapshot.

BLK-2026-04-22-007 Day 2 (Session 7 Sub-mission 2b): shipped as an independent utility class so the client builder can hold a reference and future request-routing layers can consult it without reshaping existing APIs.

Clients populate this cache by issuing a PARTITION_TABLE_REQUEST RPC and calling update(PartitionTablePayload) with the parsed response payload. The cache accepts the new snapshot iff its revision is strictly greater than the currently-stored revision — out-of-order responses (two concurrent refreshes where the older one landed after the newer one) are silently dropped. The server's strictly-monotonic rebalance counter in PartitionRouter.getRevision() guarantees the ordering semantics.

Routing helpers: ownerGroupForKey(String) and ownerGroupForHash(int) both consult the cached snapshot. When the cache is empty (before first refresh, or after an explicit clear()), both methods return -1 so callers can degrade to their existing hash-by-active-nodes or round-robin routing.

Full wire-up into RequestRouter.selectNode is tracked under Session 8 per the Session 7 closeout — this class is the minimum-viable building block shipping in Session 7.

Thread-safety: all methods are safe for concurrent access. Snapshot installation is lock-free via AtomicReference.compareAndSet(V, V).

Since:
2.1

  • Field Details

    • NO_OWNER

      public static final int NO_OWNER
      Sentinel returned when the cache has never been populated.
      See Also:

  • Constructor Details

    • ClientPartitionTable

      public ClientPartitionTable()

  • Method Details

    • update

      public boolean update(PartitionTablePayload payload)
      Install a newer partition-table snapshot. Drops the update if its revision is not strictly greater than the currently-stored revision.
      Parameters:
      payload - the freshly-received snapshot (non-null)
      Returns:
      true iff this call made payload the current snapshot

    • ownerGroupForKey

      public int ownerGroupForKey(String key)
      Returns:
      the owning Raft group id for key, or NO_OWNER when no snapshot has been cached yet. Uses MurmurHash3 to partition the key and then looks up the owner in the snapshot.

    • ownerEndpointForKey

      public @Nullable String ownerEndpointForKey(String key)
      Returns:
      the advertised leader/owner endpoint for the group owning key, or null when no snapshot or endpoint metadata exists

    • ownerEndpointForHash

      public @Nullable String ownerEndpointForHash(int hash)
      Returns:
      the advertised leader/owner endpoint for the group owning hash, or null when no snapshot or endpoint metadata exists

    • leaderEndpointForOwnerGroup

      public @Nullable String leaderEndpointForOwnerGroup(int ownerGroup)
      Returns:
      the advertised leader/owner endpoint for ownerGroup, or null when the snapshot has no endpoint metadata for that group

    • ownerGroupForHash

      public int ownerGroupForHash(int hash)
      Returns:
      the owning Raft group id for a pre-hashed key, or NO_OWNER if no snapshot has been cached. Caller is responsible for hashing with the same algorithm (MurmurHash3) the server uses.

    • currentRevision

      public long currentRevision()
      Returns:
      the revision of the cached snapshot, or -1 if no snapshot is cached. Monotonically non-decreasing across successful update(PartitionTablePayload) calls.

    • currentSnapshot

      public @Nullable PartitionTablePayload currentSnapshot()
      Returns:
      the currently-cached snapshot, or null if none has been installed yet. The returned payload is immutable in user-facing semantics (defensive copy on mutator).

    • clear

      public void clear()
      Discard the current snapshot. Next ownerGroupForKey(String) call will return NO_OWNER until a fresh snapshot is installed.

    • hashKey

      public static int hashKey(String key)
      Utility for tests and callers that hash keys themselves.
      Returns:
      MurmurHash3.hash(String) of key's UTF-8 bytes

    • hashBytes

      public static int hashBytes(byte[] bytes)
      Utility: hash raw bytes (for callers that already have the wire form).