Spring Boot

This guide is the supported Spring Boot integration path for DSM. Use it when you want runtime creation, collection registration, and lifecycle management driven by configuration and beans instead of manual bootstrap code.

What The Starter Does

The starter builds a DsmRuntime from dsm.* properties, validates collection definitions, registers configured collections, starts lifecycle management, and exposes collection handles as beans.

For most teams, that means:

1. declare the starter dependency
2. provide supporting codec and factory beans
3. describe collections in application.yml
4. inject typed collection handles into your service beans

Add The Starter

<dependency>
  <groupId>com.leanowtech.dsm</groupId>
  <artifactId>dsm-spring-boot-starter</artifactId>
  <version>${dsm.version}</version>
</dependency>

Required High-Level Properties

These two properties are required for every Spring Boot integration:

• dsm.cluster-id
• dsm.service-id

They define the DSM isolation boundary and service-family identity. Keep them stable across nodes that should belong to the same logical DSM deployment.

Supporting Beans By Collection Type

Register Collections

Required bean:

• DsmEntityCodec<E> referenced by codec-bean

Lease Collections

Required beans:

• DsmEntityCodec<E> referenced by codec-bean
• Function<String, E> referenced by lease.entity-factory-bean

Important runtime rule:

• Spring currently supports only AUTONOMOUS lease mode on this path

CRDT Collections

Required beans:

• DsmEntityCodec<E> referenced by codec-bean
• MergeableStateCodec<S> referenced by crdt.state-codec-bean
• initial state bean referenced by crdt.initial-state-bean
• StateMerger<E, S> referenced by crdt.merger-bean

Minimal Configuration Example

dsm:
  cluster-id: runtime-example
  service-id: gateway-service
  cluster:
    mode: STANDALONE
  collections:
    - bean-name: routeHintsCollection
      tenant-id: shared
      application-id: gateway
      collection-id: route-hints
      schema-id: route-hints/v1
      type: REGISTER
      consistency-tier: REGISTER
      codec-bean: routeHintCodec

Mixed Register, Lease, And CRDT Example

dsm:
  cluster-id: runtime-example
  service-id: gateway-service
  runtime:
    dynamic-registration: false
  cluster:
    mode: UNICAST
    unicast:
      gossip-port: 4447
      gossip-interval: 1s
      gossip-fanout: 3
      failure-threshold: 5
      seed-nodes:
        - 10.0.0.11:4447
        - 10.0.0.12:4447
  security:
    enabled: true
    cluster-secret: ${DSM_CLUSTER_SECRET}
    nonce:
      window-size: 1024
      max-clock-drift: 5s
  collections:
    - bean-name: routeHintsCollection
      tenant-id: shared
      application-id: gateway
      collection-id: route-hints
      schema-id: route-hints/v1
      type: REGISTER
      consistency-tier: REGISTER
      codec-bean: routeHintCodec

    - bean-name: shardOwnersCollection
      tenant-id: shared
      application-id: worker
      collection-id: shard-owner
      schema-id: shard-owner/v1
      type: LEASE
      consistency-tier: LEASE
      codec-bean: shardOwnerCodec
      lease:
        mode: AUTONOMOUS
        term: 10s
        renew-skew: 3s
        expiry-grace: 500ms
        entity-factory-bean: shardOwnerEntityFactory

    - bean-name: requestCounterCollection
      tenant-id: shared
      application-id: billing
      collection-id: request-counter
      schema-id: request-counter/v1
      type: CRDT
      consistency-tier: CRDT
      codec-bean: requestCounterCodec
      crdt:
        state-codec-bean: requestCounterStateCodec
        initial-state-bean: requestCounterInitialState
        merger-bean: requestCounterMerger

Property Validation Rules That Matter

The Spring integration validates collection definitions before runtime assembly. The most important rules are:

• every collection must set tenant-id, application-id, collection-id, schema-id, and codec-bean
• every collection locator must be unique
• bean-name, when present, must be unique
• register collections must declare consistency-tier: REGISTER
• lease collections must declare consistency-tier: LEASE
• CRDT collections must declare consistency-tier: CRDT
• lease renew-skew must be smaller than term
• referenced supporting beans must exist

Cluster Modes

Mode	Property	Best fit
Standalone	dsm.cluster.mode=STANDALONE	local development, demos, single-node experiments
Multicast	dsm.cluster.mode=MULTICAST	trusted LAN or VPC environments where multicast is available
Unicast	dsm.cluster.mode=UNICAST	Kubernetes and cloud deployments

Node Properties

• dsm.node.id default: random UUID
• dsm.node.host default: resolved local host address
• dsm.node.port default: 9090

Multicast Properties

• dsm.cluster.multicast.group default: 239.0.77.1
• dsm.cluster.multicast.port default: 4446
• dsm.cluster.multicast.heartbeat-interval default: 1s
• dsm.cluster.multicast.failure-threshold default: 5

Unicast Properties

• dsm.cluster.unicast.gossip-port default: 4447
• dsm.cluster.unicast.gossip-interval default: 1s
• dsm.cluster.unicast.gossip-fanout default: 3
• dsm.cluster.unicast.failure-threshold default: 5
• dsm.cluster.unicast.seed-nodes default: empty list
• dsm.cluster.unicast.dns.hostname optional
• dsm.cluster.unicast.dns.port default: 9090

Collection Bean Naming And Injection

Each configured collection handle is exposed as a Spring bean.

Naming rules:

• if bean-name is set, it becomes an alias you can inject by name or qualifier
• a stable bean name is always registered as dsmCollection:<tenant>/<application>/<collection>

Example injection by explicit alias:

@Service
public class RouteHintService {

    private final DsmRegister<RouteHint> routeHints;

    public RouteHintService(@Qualifier("routeHintsCollection") DsmRegister<RouteHint> routeHints) {
        this.routeHints = routeHints;
    }
}

Runtime Customization Hooks

If you need to customize the builder before the runtime is built, provide a DsmRuntimeBuilderCustomizer bean.

This is the right place for advanced setup such as a custom collection store, custom registry, or clock override.

What Gets Auto-Configured

The Spring path creates or exposes these core beans:

• NodeInfo
• ClusterMembership
• DsmRuntime
• DsmCollectionRegistry
• DsmRuntimeLifecycle
• DsmRuntimeRegistrationReporter
• DsmMetrics

When To Use The Reference Pages

Use the Spring guide for the integration sequence. Use the reference pages when you need exact field-level detail.

• Spring Properties
• Collection Specs
• Collection Handles