Skip to main content
FlowWarden is zero-config by design. Almost everything — checkpoint behavior, retry policies, DLQ policy, deployment strategy — is configured per-stream via annotations on your @ChangeStream classes. A small number of properties exist for application-wide concerns: execution mode and backend-level defaults.

​
Application Properties

PropertyTypeDefaultDescription
flowwarden.default-modeIMPERATIVE | REACTIVEIMPERATIVEExecution mode for all FlowWarden streams in the application.
flowwarden.dlq.mongo.collectionString_fw_dlqBackend-level default MongoDB collection for the Dead Letter Queue. Per-stream override via @MongoDlqOptions(collection = ...).
flowwarden:
  default-mode: IMPERATIVE   # or REACTIVE
  dlq:
    mongo:
      collection: _fw_dlq    # global default; per-stream override via @MongoDlqOptions
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.

​
flowwarden.dlq.mongo

The MongoDB-backed DlqStore writes failed events to a single default collection unless a stream opts out via @MongoDlqOptions. The TTL index on expiresAt is created at startup for every collection bound to a @DeadLetterQueue-annotated stream.
PropertyTypeDefaultDescription
flowwarden.dlq.mongo.collectionString_fw_dlqDefault collection name used when a stream does not declare @MongoDlqOptions(collection = ...).
This namespace is Mongo-specific. Other backends (Kafka, RabbitMQ, JDBC) ship analogous property prefixes (flowwarden.dlq.kafka.*, etc.) once their DlqStore implementations land.

​
ExecutionMode values

ValueDescription
IMPERATIVEBlocking mode. Uses Spring’s MongoTemplate with dedicated threads. Handler methods return void.
REACTIVENon-blocking mode. Uses ReactiveMongoTemplate and Project Reactor. Handler methods return Mono<Void>.
The mode is application-wide — you cannot mix imperative and reactive handlers in the same application. See Handler Signatures for the validation rules.

​
What is configured by annotation, not by property

Most behavior settings live on per-stream annotations, not on application.yml:
ConcernWhere to configure
Resume token persistence frequency@Checkpoint (saveEveryN, saveIntervalSeconds)
Retry behavior on failure@RetryPolicy (maxAttempts, initialDelay, multiplier, maxDelay, jitter, retryOn, noRetryOn)
Dead Letter Queue policy@DeadLetterQueue (enabled, retentionDays, includeOriginalDocument, includeStackTrace)
Mongo-specific DLQ collection@MongoDlqOptions (collection) — backend companion to @DeadLetterQueue
Multi-instance coordination@ChangeStream(deploymentMode = ...)
Server-side filtering@Pipeline
Application-side filtering@Filter
Custom error handling@OnError
Multi-database routing@ChangeStream(mongoTemplateRef = ...)
This keeps stream configuration next to the code that uses it, instead of fragmenting it between annotations and YAML.

​
MongoDB connection

FlowWarden uses Spring Data MongoDB’s auto-configured MongoTemplate (or ReactiveMongoTemplate). Configure the connection with standard Spring properties: 
spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/mydb
MongoDB must be configured as a Replica Set for Change Streams to work. This applies to development environments as well. Testcontainers provisions a single-node Replica Set automatically for tests.

​
Disabling FlowWarden globally

To disable all streams without removing the @EnableFlowWarden annotation, set the attribute on the annotation itself: 
@SpringBootApplication
@EnableFlowWarden(enabled = false)
public class MyApplication { }
This is useful for maintenance mode or environment-specific profiles where streams should not start. See @EnableFlowWarden.

​
See Also

@EnableFlowWarden

Auto-configuration entry point and global on/off switch.

@ChangeStream

Per-stream attributes — the main place to configure behavior.

Handler Signatures

Mode-dependent return type rules.

Actuator

Operational endpoints and metrics.