What Is DSM?

DSM is an open-source Distributed Shared Memory toolkit for enterprise Java services. It gives service teams a runtime-first way to replicate control-plane data across nodes without adopting a general-purpose database platform inside every service.

Runtime Picture

What DSM Solves

DSM is designed for data that has to be shared and coordinated across a service family:

• route hints and service-local discovery metadata
• shard or partition ownership
• low-volume replicated configuration
• convergent counters and mergeable state

The core idea is simple: your application code talks to collection handles, DsmRuntime stamps and records the change, and the sync layer replicates those deltas across the cluster.

A Concrete Example

The standalone example in dsm-examples starts one runtime with three collections:

• register: shared/gateway/route-hints
• CRDT: shared/worker/request-counter
• lease: shared/worker/shard-owner

That gives you three different kinds of shared state in one process:

Locator	Example entry	Coordination meaning
shared/gateway/route-hints	edge-eu-west-1 -> 10.1.0.8:8443	Gateway-visible routing metadata.
shared/worker/shard-owner	shard-17 -> worker-a, fencing token 42	Current ownership for one work shard.
shared/worker/request-counter	merged cluster counter	Convergent aggregate across workers.

The collection locator is always three-part:

tenantId/applicationId/collectionId.

Concrete locators in the example are shared/gateway/route-hints, shared/worker/shard-owner, and shared/worker/request-counter.

Why Teams Use It

• It keeps coordination inside the service that owns the workflow.
• It exposes explicit runtime boundaries: clusterId, serviceId, tenantId, applicationId, and collectionId.
• It supports three different coordination models in one API surface: registers, leases, and CRDTs.
• It ships with security, diagnostics, and Spring Boot support instead of leaving those as integration debt.

What DSM Is Not

DSM is not a general-purpose OLTP store, analytics engine, or document database. It is optimized for replicated metadata and coordination state where deterministic runtime behavior matters more than bulk storage throughput.

Use a database when you need rich querying, large document payloads, or system-of-record guarantees.

Use DSM when you need fast shared coordination state inside a service family.

Core Runtime Flow

1. Application code mutates a collection handle.
2. DsmRuntime stamps entity metadata and records the change locally.
3. RuntimePlatformSyncService replicates register, lease, and CRDT deltas through platform envelopes.
4. RuntimeDataPlaneReplicationService repairs lagging peers using digest, snapshot, and replay flows.

In practice, this means a register put(...) does not talk directly to every peer. The local runtime commits the update first, then the sync layer transports the delta, and repair catches up any peer that missed it.

What The Identifiers Mean

DSM has several identifiers. They are not interchangeable.

Identifier	Meaning
clusterId	Which DSM cluster is this?
serviceId	Which service family is allowed to join it?
tenantId	Which tenant or high-level owner does the data belong to?
applicationId	Which application domain owns the collection?
collectionId	Which exact collection is being replicated?

Example:

Identifier	Example value
clusterId	prod-eu-west-cluster
serviceId	gateway-service
tenantId	shared
applicationId	gateway
collectionId	route-hints

If clusterId or serviceId is wrong, nodes should not share runtime traffic. If the collection locator is wrong, peers may reject or misroute replicated data.

Deployment Boundary Rules

clusterId and serviceId are required isolation boundaries. Keep them stable for a deployed DSM cluster and service family. In practice:

• clusterId separates one DSM cluster from another.
• serviceId ensures only related services participate in the same runtime fabric.

Recommended rule: use different clusterId values for local, staging, and production, and keep serviceId stable per deployed service family.

Where To Go Next

• Read Getting Started for the minimum standalone setup.
• Read Collection Types before modeling data.
• Read Spring Boot if you want autoconfiguration and property-driven registration.
• Read Runtime API and Spring Properties when you need exact interface and configuration detail.
• Read Service Discovery & Routing, Shard Owner Election, and Distributed Counters for scenario-driven patterns.