Chapter 16 — Assemble Runtime with Spring Boot

Chapter objective: After this chapter, a developer can create Runtime and named collection beans from dsm.* properties, understand auto-configuration gates, and validate context and lifecycle behavior.

Learning objectives

1. Explain the assembly order of DsmProperties, DsmAutoConfiguration, and collection beans.
2. Configure clusterId, serviceId, membership, and three collection types.
3. Inject a typed handle or domain adapter by bean name.
4. Fail fast on invalid configuration during startup.

Prerequisites

• The domain port and composition root from Chapter 15 are complete.
• Spring Boot configuration properties and bean lifecycle are familiar.
• Successful context startup is distinct from validated multi-node networking.

Case progress

The fulfillment application replaces manual builders with application.yml. Auto-configuration creates membership and Runtime, registers named collection beans, then injects them into the DSM domain adapter.

From configuration to domain port

The order is structural: collection registration needs Runtime; the domain adapter needs registered handles; shutdown lifecycle stops Runtime.

Minimal property contract

The Chapter 16 asset contains complete configuration for three collection types. Key fields include:

dsm:
  cluster-id: fulfillment
  service-id: fulfillment-control-plane
  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
      entity-type: com.example.RouteHint

Referenced classes and codec/merger/entity factories need to exist. The full teaching asset uses placeholder com.example.* types for configuration review; it is not presented as a startable application. Startup evidence comes from pinned DsmAutoConfigurationTest and SpringBootDsmApplicationTest sources.

Two forms of bean name

Auto-configuration creates a canonical locator-based name:

dsmCollection:shared/gateway/route-hints

Configured bean-name supplies a business-friendly alias such as routeHintsCollection. Both resolve to the same registration. The adapter uses an explicit qualifier instead of asking the container to infer a target from erased generic types.

Record codec convenience and boundary

When entity-type is a record, auto-configuration can derive a RecordCodec. A non-record without codec-bean fails startup. CRDT also requires state codec, initial state, and merger; Lease requires an entity factory.

Fail-fast behavior locates an assembly error during startup instead of waiting for the first remote message.

Startup gates

DsmAutoConfigurationTest fixes these outcomes:

Counterexample and fault injection

Copy the configuration asset, remove the CRDT merger bean, or assign one locator to two collections. The context should reject startup at the configuration boundary instead of delaying failure until a business action.

Experiment

cd submodule/dsm
mvn -q -pl dsm-spring-boot-autoconfigure -am \
  -Dtest=DsmAutoConfigurationTest,DsmSpringBootSmokeTest \
  -Dsurefire.failIfNoSpecifiedTests=false test

Run the real example application context:

cd submodule/dsm-examples/basic-usage-examples
./mvnw -q -Dtest=SpringBootDsmApplicationTest test

Experiment acceptance card

Review

• Spring Boot changes assembly, not collection semantics or failure boundaries.
• Runtime precedes collections; collections precede the adapter.
• Canonical locator names and business aliases remain explicit, stable, and testable.
• Invalid configuration fails at startup rather than degrading silently at runtime.

Next

Chapter 17 separates two identity layers: clusterId/serviceId controls the communication domain and locator controls the collection domain.

Evidence links

• DsmProperties
• DsmAutoConfiguration
• DsmAutoConfigurationTest
• SpringBootDsmApplicationTest