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
  • changes(): opens a default change stream
  • changes(ChangeStreamOptions): opens a change stream with explicit replay, buffer, and overflow behavior

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

Change streams are not durable event logs. They are local observation surfaces for audit hooks, devtools, federation live forwarding, and cache invalidation. If a consumer must replay every event after a crash, use a durable queue or outbox outside DSM.

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.

Size Change Streams Intentionally ​

Bounded change streams can drop, block, or fail fast depending on OverflowPolicy. OverflowPolicy.ERROR surfaces ChangeStreamOverflowException with DSM-9001; sustained overflow means the consumer is too slow or the workflow needs a durable event pipeline.