@JaversStream - FlowWarden

The @JaversStream annotation declares a handler class that watches Javers audit snapshots for changes to a specific entity type. It is the entry point for the FlowWarden Javers integration module.

Basic Usage

@JaversStream(entityType = Product.class)
public class ProductAuditHandler {

    @OnInitial
    void onCreated(Product product, JaversChangeContext<Product> ctx) {
        log.info("Product created: {}", product.getName());
    }

    @OnUpdate
    void onUpdated(Product product, JaversChangeContext<Product> ctx) {
        log.info("Product updated: {} — changed: {}", product.getName(),
            ctx.getChangedProperties());
    }
}

@JaversStream requires the flowwarden-javers module on your classpath. The auto-configuration activates only when Javers is detected.

Attributes Reference

Attribute	Type	Default	Description
`entityType`	`Class<?>`	(required)	The domain entity type to watch. FlowWarden filters snapshots by this type’s fully qualified class name.
`name`	`String`	`""` (kebab-case of class name)	Unique stream name. Used in logs, checkpoints, and metrics.
`snapshotCollection`	`String`	`""` (auto-detect)	Javers snapshot collection name. If empty, resolved from `javers.snapshotCollectionName` property, then defaults to `jv_snapshots`.
`database`	`String`	`""` (Spring default)	MongoDB database name.
`autoStart`	`boolean`	`true`	Whether the stream starts automatically on application startup.

Compatible Annotations

The following FlowWarden annotations can be combined with @JaversStream:

Annotation	Purpose
`@Checkpoint`	Resume token persistence for crash recovery
`@RetryPolicy`	Exponential backoff retry on handler failure
`@RestartPolicy`	Cadence and ceiling of the managed restart loop after a cursor death (since stream-core `1.0.0-rc.7`)
`@DeadLetterQueue` / `@MongoDlqOptions`	Route failed events to a DLQ collection

@Filter and @Pipeline are not supported: the stream watches the whole snapshot collection and filters by entity type internally.

Handler Annotations

Annotation	Javers Type	Description
`@OnInitial`	`INITIAL`	First snapshot — entity creation
`@OnUpdate`	`UPDATE`	Subsequent modifications
`@OnTerminal`	`TERMINAL`	Entity deletion

How It Works Internally

JaversStreamContributor, a stream-core StreamDefinitionContributor, finds the beans annotated with @JaversStream once all singletons are created
Declares each one as a StreamSpec watching the Javers snapshot collection — a single onInsert handler (every Javers snapshot is an insert), fullDocument = UPDATE_LOOKUP, the policy annotations mapped to their specs, and the Javers handler names (JAVERS_OnInitial, …) reported to monitoring through handlerNames
stream-core validates and registers it like any contributed stream — the module uses no stream-core internals
On each snapshot insert, an internal dispatcher:
- Filters by globalId.entity matching the configured entityType
- Deserializes the state field into the domain object via Spring’s MongoConverter
- Reconstructs the CdoSnapshot via Javers’ JSON converter
- Dispatches to the matching @OnInitial, @OnUpdate, or @OnTerminal handler

​Basic Usage

​Attributes Reference

​Compatible Annotations

​Handler Annotations

​How It Works Internally

Basic Usage

Attributes Reference

Compatible Annotations

Handler Annotations

How It Works Internally