DSM

Appearance

Runtime API Reference ​

This page documents the public runtime facade used by integration code.

Runtime Layers ​

DSM exposes a small hierarchy of runtime interfaces:

  • DsmRuntime: root facade for lifecycle, registry, diagnostics, and direct collection registration
  • TenantRuntime: tenant-scoped view
  • ApplicationRuntime: tenant plus application scoped view for registering collections under one locator prefix

Typical access flow:

java
DsmRuntime runtime = ...;
ApplicationRuntime gateway = runtime.tenant("shared").application("gateway");

DsmRuntime ​

DsmRuntime is the main runtime contract.

Identity And Topology ​

  • info(): returns immutable runtime identity information
  • clusterView(): returns the current membership snapshot
  • registry(): returns the shared collection registry

Use these APIs when exposing admin or diagnostics endpoints.

Scoped Access ​

  • tenant(String tenantId): returns a tenant-scoped runtime view

Use tenant/application scoping when you want registration code organized by domain boundary instead of passing tenant/application strings repeatedly.

Collection Registration ​

  • register(CollectionSpec<E> spec)
  • leaseRegister(LeaseCollectionSpec<E> spec)
  • crdt(CrdtCollectionSpec<E, S> spec, StateMerger<E, S> merger)

Each registration call returns a live typed handle.

Recommended practice:

  • register during bootstrap when the collection set is fixed
  • keep the returned handle in a service-owned integration adapter
  • avoid repeated ad hoc lookups and registrations across unrelated packages

Lifecycle And Readiness ​

  • start(): starts runtime lifecycle components
  • state(): returns the current runtime state
  • isReady(): returns whether the runtime is ready for local work
  • close(): shuts down the runtime

Important rule: creating the runtime does not start it. Call start() explicitly unless your hosting framework manages that for you.

Diagnostics ​

  • diagnostics(): returns a runtime-wide diagnostics snapshot

Use diagnostics during local validation and production troubleshooting. It is the first API to inspect before assuming a replication bug.

DsmRuntimeBuilder ​

DsmRuntimeBuilder assembles one runtime instance.

Required Inputs ​

  • clusterId(String)
  • serviceId(String)
  • membership(ClusterMembership)

If serviceId is omitted, the builder will try membership.serviceId(). If neither provides a non-blank value, runtime construction fails.

Optional Customization ​

  • collectionRegistry(DsmCollectionRegistry)
  • collectionStore(RuntimeCollectionStore)
  • collectionSpecValidator(CollectionSpecValidator)
  • allowDynamicRegistration(boolean)
  • clock(Clock)

Most integrations should start with defaults and override only when there is a concrete operational reason.

Bootstrap Registration Methods ​

  • register(CollectionSpec<E>)
  • leaseRegister(LeaseCollectionSpec<E>)
  • crdt(CrdtCollectionSpec<E, S>, StateMerger<E, S>)

These queue collection registrations on the builder so the runtime is created with a known bootstrap set.

Build ​

  • build() returns one DsmRuntime

TenantRuntime ​

TenantRuntime is a narrow interface used to scope work to one tenant.

  • tenantId()
  • application(String applicationId)

Use it when your service naturally groups collections per tenant.

ApplicationRuntime ​

ApplicationRuntime scopes registration to one tenant and one application.

  • tenantId()
  • applicationId()
  • register(CollectionSpec<E>)
  • leaseRegister(LeaseCollectionSpec<E>)
  • crdt(CrdtCollectionSpec<E, S>, StateMerger<E, S>)

Use it when one service module owns multiple collections under the same tenant/application pair.

Runtime Identity Concepts ​

clusterId ​

Defines the DSM cluster boundary. Nodes with different cluster IDs should not behave as one cluster.

serviceId ​

Defines the service-family boundary inside a DSM cluster. Keep it stable for all peers participating as the same service family.

Node Identity ​

Node identity comes from the selected membership implementation and local NodeInfo.

Lifecycle Guidance ​

Recommended service lifecycle:

  1. construct membership
  2. build runtime
  3. register collections if not already queued on the builder
  4. call start()
  5. serve application traffic
  6. call close() during shutdown