Skip to main content

​
Overview

@EnableFlowWarden activates the FlowWarden framework. Place it on a @Configuration or @SpringBootApplication class. It is a marker annotation — it does not perform package scanning itself. @ChangeStream classes are discovered through Spring’s standard @ComponentScan (since @ChangeStream is meta-annotated with @Component), and ChangeStreamBeanPostProcessor inspects all beans in the context to find those annotated with @ChangeStream. At startup, FlowWarden will:
  1. Discover all @ChangeStream beans from the Spring application context
  2. Validate the configuration — execution mode, MongoDB template availability, handler signatures
  3. Register discovered streams in the internal registry
  4. Start streams with autoStart = true after the Spring context is ready

​
Minimal Setup

@SpringBootApplication
@EnableFlowWarden
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}
Your @ChangeStream classes just need to be picked up by Spring’s @ComponentScan — which happens automatically when they are in the same package (or a sub-package) as your @SpringBootApplication class.

​
Attributes

AttributeTypeDefaultDescription
propertyPrefixString"flowwarden.stream"Prefix for FlowWarden configuration properties
enabledbooleantrueGlobally enable or disable all streams
@EnableFlowWarden does not have basePackages or basePackageClasses attributes. Handler discovery relies on Spring’s standard @ComponentScan. If you need to restrict which @ChangeStream classes are loaded (e.g., in tests), use Spring’s own @ComponentScan(basePackages = ...) or @SpringBootTest(classes = ...).

​
Configuration

The execution mode defaults to IMPERATIVE when not explicitly configured. For Spring WebFlux applications, set it to REACTIVE in application.yml: 
flowwarden:
  default-mode: REACTIVE   # defaults to IMPERATIVE if omitted
If flowwarden.default-mode is not set, FlowWarden defaults to IMPERATIVE and logs:
INFO  FlowWardenConfigurationValidator - No 'flowwarden.default-mode' configured, defaulting to IMPERATIVE
Spring MVC applications can omit this property entirely. Spring WebFlux applications must set it to REACTIVE explicitly.

​
How Auto-Configuration Works

FlowWarden uses Spring Boot’s auto-configuration mechanism. When @EnableFlowWarden is present, three auto-configuration classes activate in order:
ClassConditionProvides
FlowWardenAutoConfigurationAlwaysChangeStreamBeanPostProcessor, FlowWardenConfigurationValidator
ImperativeFlowWardenAutoConfigurationflowwarden.default-mode=IMPERATIVE (or missing)ImperativeStreamManager, CheckpointStore → MongoCheckpointStore
ReactiveFlowWardenAutoConfigurationflowwarden.default-mode=REACTIVEReactiveStreamManager, CheckpointStore → ReactiveMongoCheckpointStore
The FlowWardenConfigurationValidator runs after all singleton beans are created (SmartInitializingSingleton) and checks:
  1. Mode is resolved — flowwarden.default-mode defaults to IMPERATIVE if not set
  2. Template available — IMPERATIVE requires MongoTemplate, REACTIVE requires ReactiveMongoTemplate
All errors follow the Spring Boot error format with a Description and an Action section suggesting how to fix the issue.

​
Disabling FlowWarden

Set enabled = false to disable all stream processing without removing the annotation: 
@SpringBootApplication
@EnableFlowWarden(enabled = false)
public class MyApplication { }
This is useful for running the application in a degraded mode (e.g., maintenance) or for profiles where streams should not start.

​
Full Example

@SpringBootApplication
@EnableFlowWarden
public class SampleSpringMvcApplication {
    public static void main(String[] args) {
        SpringApplication.run(SampleSpringMvcApplication.class, args);
    }
}
application.yml
flowwarden:
  default-mode: IMPERATIVE   # or REACTIVE

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/mydb   # Must be a Replica Set

​
See Also

Quickstart

Full getting-started guide with dependency setup

@ChangeStream

Declare a Change Stream handler class

Imperative vs Reactive

Choose the right execution mode

Configuration

All FlowWarden configuration properties