5. Moments — a Passage of Time Events API

spring-modulith-moments is a Passage of Time Events implementation heavily inspired by Matthias Verraes blog post. It’s an event-based approach to time to trigger actions that are tied to a particular period of time having passed.spring-doc.cn

To use the abstraction, include the following dependency in your project:spring-doc.cn

<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-moments</artifactId>
</dependency>

The dependency added to the project’s classpath causes the following things in your application:spring-doc.cn

  • Application code can refer to HourHasPassed, DayHasPassed, WeekHasPassed, MonthHasPassed, QuarterHasPassed, YearHasPassed types in Spring event listeners to get notified if a certain amount of time has passed.spring-doc.cn

  • A bean of type org.springframework.modulith.Moments is available in the ApplicationContext that contains the logic to trigger these events.spring-doc.cn

  • If spring.modulith.moments.enable-time-machine is set to true, that instance will be a org.springframework.modulith.TimeMachine which allows to "shift" time and by that triggers all intermediate events, which is useful to integration test functionality that is triggered by the events.spring-doc.cn

By default, Moments uses a Clock.systemUTC() instance. To customize this, declare a bean of type Clock.spring-doc.cn

@Configuration
class MyConfiguration {

  @Bean
  Clock myCustomClock() {
    // Create a custom Clock here
  }
}

Moments exposes the following application properties for advanced customization:spring-doc.cn

Table 1. Available application properties
Property Default value Description

spring.modulith.moments.enable-time-machinespring-doc.cn

falsespring-doc.cn

If set to true, the Moments instance will be a TimeMachine, that exposes API to shift time forward. Useful for integration tests that expect functionality triggered by the Passage of Time Events.spring-doc.cn

spring.modulith.moments.granularityspring-doc.cn

hoursspring-doc.cn

The minimum granularity of events to be fired. Alternative value days to avoid hourly events.spring-doc.cn

spring.modulith.moments.localespring-doc.cn

Locale.getDefault()spring-doc.cn

The Locale to use when determining week boundaries.spring-doc.cn

spring.modulith.moments.quarter-start-monthspring-doc.cn

Months.JANUARYspring-doc.cn

The month at which quarters start.spring-doc.cn

spring.modulith.moments.zone-idspring-doc.cn

ZoneOffset#UTCspring-doc.cn

The ZoneId to determine times which are attached to the events published.spring-doc.cn