DSM

Appearance

Collection Handles Reference ​

This page documents the public collection handle interfaces returned by the runtime.

Shared Base Interface ​

All collection handles extend DsmCollection<E>.

Shared methods:

  • spec(): returns the immutable collection specification
  • locator(): returns the collection locator
  • diagnostics(): returns a lightweight diagnostics snapshot for that collection

These methods are useful for admin endpoints, diagnostics, and generic wrappers.

DsmRegister<E> ​

Register collections store one latest value per entry key.

Methods ​

  • put(E entity): insert or replace the entity under its entry key
  • get(String entryKey): look up one entity by key
  • all(): return all locally known entities
  • remove(String entryKey): remove one entity by key
  • size(): return the local entry count

Example ​

java
routeHints.put(new RouteHint("orders", null, "10.0.0.12:8443"));

Optional<RouteHint> route = routeHints.get("orders");
List<RouteHint> all = routeHints.all();
Optional<RouteHint> removed = routeHints.remove("orders");
int size = routeHints.size();

Best Fit ​

Use a register when you need simple replicated metadata with explicit overwrites.

DsmLeaseRegister<E> ​

Lease collections expose ownership operations and current lease snapshots.

Methods ​

  • acquire(String key, LeaseAcquireOptions options)
  • renew(String key, LeaseRenewOptions options)
  • transfer(String key, String targetNodeId, LeaseTransferOptions options)
  • release(String key, LeaseReleaseOptions options)
  • current(String key)
  • addLeaseListener(LeaseListener<E> listener)

All mutating lease operations return CompletableFuture<...> because the outcome may depend on coordination and current lease state.

Example ​

java
LeaseAcquireResult<ShardOwner> result = shardOwners.acquire(
        "shard-17",
        LeaseAcquireOptions.defaults())
    .join();

shardOwners.current("shard-17")
    .ifPresent(snapshot -> System.out.println(snapshot.ownerNodeId()));

Best Fit ​

Use a lease collection when the key question is not just "what is the latest value" but "who currently owns this work item".

DsmCrdtCollection<E, S> ​

CRDT collections hold mergeable state and accept state updates as entities.

Methods ​

  • state(): return the current merged state
  • apply(E entity): apply one update entity
  • versionVector(): return the current version vector
  • deltaSince(VersionVector versionVector): compute a delta for a peer that last saw the supplied version vector

Example ​

java
counters.apply(PnCounterUpdate.increment("invoice-42", 1));

PnCounterState state = counters.state();
VersionVector version = counters.versionVector();
StateDelta<PnCounterState> delta = counters.deltaSince(version);

Best Fit ​

Use a CRDT collection when multiple nodes need local writes and the runtime should merge them toward convergence.

Handle Usage Guidelines ​

Keep Handles Long-Lived ​

Treat collection handles as service-owned components. Do not repeatedly look them up or rebuild them on each request.

Wrap Them In Domain Operations ​

Prefer a domain adapter or repository that exposes business operations rather than scattering raw put, acquire, or apply calls across the codebase.

Inspect Diagnostics During Incidents ​

Every handle exposes diagnostics(). Use it before assuming the problem is outside DSM.