Clock and time

Spring DDD reads the current time through a single java.time.Clock, used for projection and saga bookkeeping: high-water-mark detection, projection lease staleness, cascade-rebuild timing, and saga deadline evaluation.

How the clock is resolved

The framework never hard-codes Instant.now() for this bookkeeping. Each component resolves its clock through Spring’s ObjectProvider<Clock>:

  • If the application context defines exactly one Clock bean — of any name — that bean drives all framework time.

  • If it defines none, the framework falls back to Clock.systemUTC().

There is no framework-provided Clock bean and no required bean name: any Clock you expose is adopted automatically.

Define at most one Clock bean. If the context contains more than one, resolution is ambiguous and startup fails with NoUniqueBeanDefinitionException — there is intentionally one clock of record per application.

Overriding the clock

Expose a Clock bean to make time deterministic — for example to pin or advance time:

@Bean
fun clock(): Clock = Clock.fixed(Instant.parse("2026-01-01T00:00:00Z"), ZoneOffset.UTC)

The bean name is irrelevant; the Clock type is what the framework resolves.

In tests

Provide a fixed (or adjustable) Clock bean in the test context to control saga deadline evaluation and lease timeouts deterministically:

@TestConfiguration
class FixedClockConfig {
    @Bean
    fun clock(): Clock = Clock.fixed(NOW, ZoneOffset.UTC)
}

Related pages