Quickstart

Prerequisites

Java 17+

Spring Boot 3.x requires Java 17 as a minimum.

Spring Boot 3.x

Spring MVC or Spring WebFlux — both are supported.

MongoDB Replica Set

Change Streams require a Replica Set. A single-node RS is fine for local dev.

MongoDB must be running as a Replica Set — Change Streams are not available on standalone instances. For local development, start MongoDB with --replSet rs0 or use a Docker Compose setup.

Step 1 — Add the dependency

<dependency>
    <groupId>io.flowwarden</groupId>
    <artifactId>flowwarden-stream-core</artifactId>
    <version>1.0.0-rc.3</version>
</dependency>

implementation 'io.flowwarden:flowwarden-stream-core:1.0.0-rc.3'

No additional dependencies needed. FlowWarden uses only Spring Data MongoDB, which is already on your classpath via spring-boot-starter-data-mongodb.

Using the BOM (optional)

If you also pull flowwarden-stream-core-testkit (for backend implementors) or future satellite modules, import the flowwarden-bom in your dependencyManagement to keep versions aligned:

Maven

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.flowwarden</groupId>
      <artifactId>flowwarden-bom</artifactId>
      <version>1.0.0-rc.3</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>io.flowwarden</groupId>
    <artifactId>flowwarden-stream-core</artifactId>
  </dependency>
</dependencies>

Step 2 — Configure your application

Add the following to your application.yml:

Spring MVC (imperative)
Spring WebFlux (reactive)

flowwarden:
  default-mode: IMPERATIVE

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/mydb?replicaSet=rs0

flowwarden:
  default-mode: REACTIVE

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/mydb?replicaSet=rs0

flowwarden.default-mode is optional — it defaults to IMPERATIVE when omitted. Only set it explicitly if you need the reactive mode.

Step 3 — Enable FlowWarden

Add @EnableFlowWarden to your main application class:

import io.flowwarden.stream.annotation.EnableFlowWarden;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@EnableFlowWarden
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

This activates the FlowWarden auto-configuration. @ChangeStream classes are discovered through Spring’s standard component scanning — @ChangeStream is meta-annotated with @Component, so no extra @ComponentScan configuration is needed.

Step 4 — Create your first handler

Declare a Spring bean annotated with @ChangeStream and add a handler method:

import io.flowwarden.stream.ChangeStreamContext;
import io.flowwarden.stream.annotation.ChangeStream;
import io.flowwarden.stream.annotation.OnChange;

@ChangeStream(documentType = Order.class)
public class OrderStream {

    @OnChange
    void handleOrderChange(ChangeStreamContext<Order> ctx) {
        System.out.println(ctx.summary());
    }
}

import io.flowwarden.stream.ChangeStreamContext;
import io.flowwarden.stream.annotation.ChangeStream;
import io.flowwarden.stream.annotation.OnChange;
import reactor.core.publisher.Mono;

@ChangeStream(documentType = Order.class)
public class OrderStream {

    @OnChange
    Mono<Void> handleOrderChange(ChangeStreamContext<Order> ctx) {
        return Mono.fromRunnable(() -> System.out.println(ctx.summary()));
    }
}

Where Order is a Spring Data @Document class:

import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.mapping.Document;

@Document(collection = "orders")
public class Order {

    @Id
    private String id;
    private String customerEmail;
    private String status;
    // getters, setters...
}

When documentType is set, FlowWarden infers the collection name from the @Document annotation (or the decapitalized class name if none). No need to repeat it in @ChangeStream(collection = "orders").

Step 5 — Run it

Start your application. On boot, you will see a log line for each discovered stream:

INFO  i.f.s.i.d.ChangeStreamBeanPostProcessor - Discovered Change Stream 'order-stream' on collection 'orders' (handlers: @OnChange=handleOrderChange, checkpoint: false, retryPolicy: false, dlq: false, onError: false)

Then insert a document in the orders collection — your handler fires immediately.

MongoDB shell

db.orders.insertOne({ customerEmail: "alice@example.com", status: "PENDING", total: 49.99 })

What’s next?

How it Works

Understand the startup lifecycle and the event processing pipeline

Typed handlers

Use @OnInsert, @OnUpdate, @OnDelete for operation-specific logic

Checkpoint & Resume

Survive restarts without missing or replaying events

Filtering Events

Push aggregation pipelines to MongoDB or filter in Java

Getting Started

FAQ

Guides

Prerequisites

Java 17+

Spring Boot 3.x

MongoDB Replica Set

Step 1 — Add the dependency

Using the BOM (optional)

Step 2 — Configure your application

Step 3 — Enable FlowWarden

Step 4 — Create your first handler

Step 5 — Run it

What’s next?

How it Works

Typed handlers

Checkpoint & Resume

Filtering Events

​Prerequisites

Java 17+

Spring Boot 3.x

MongoDB Replica Set

​Step 1 — Add the dependency

​Using the BOM (optional)

​Step 2 — Configure your application

​Step 3 — Enable FlowWarden

​Step 4 — Create your first handler

​Step 5 — Run it

​What’s next?

How it Works

Typed handlers

Checkpoint & Resume

Filtering Events

Prerequisites

Step 1 — Add the dependency

Using the BOM (optional)

Step 2 — Configure your application

Step 3 — Enable FlowWarden

Step 4 — Create your first handler

Step 5 — Run it

What’s next?