Handler Signatures

This page is the focused reference for all supported handler method signatures. For dispatch semantics, multi-annotation combinations, and validation errors, see Event Handlers.

Parameter Styles

Typed handlers (@OnInsert, @OnUpdate, @OnDelete, @OnReplace) support three parameter styles. @OnChange supports only CONTEXT_ONLY.

Style	Parameters	Notes
`CONTEXT_ONLY`	`(ChangeStreamContext<T> ctx)`	Access metadata + document via `ctx.getFullDocument()`.
`DOCUMENT_ONLY`	`(T doc)`	Receive the deserialized document directly. Requires a concrete `documentType`.
`DOCUMENT_AND_CONTEXT`	`(T doc, ChangeStreamContext<T> ctx)`	Both the document and the context. Requires a concrete `documentType`.

DOCUMENT_ONLY and DOCUMENT_AND_CONTEXT signatures fail at startup with BeanCreationException if @ChangeStream.documentType is Document.class (the default). Set a concrete class:

@ChangeStream(documentType = Order.class)

Return Types — Mode Exclusivity

The return type is bound to the configured execution mode (flowwarden.default-mode):

Mode	Required return type	Other return types
`IMPERATIVE` (default)	`void`	`Mono<Void>` is rejected at startup
`REACTIVE`	`Mono<Void>`	`void` is rejected at startup

Mixing return types across handlers in the same application is not allowed. All handler methods must consistently return void or Mono<Void> matching the configured mode. A mismatch triggers a BeanCreationException.

Other return types — CompletableFuture, Flux, String, etc. — are rejected at startup with unsupported return type.

Full Signature Matrix

Imperative (void)
Reactive (Mono)

Style	Signature
`CONTEXT_ONLY`	`void handle(ChangeStreamContext<T> ctx)`
`DOCUMENT_ONLY`	`void handle(T doc)`
`DOCUMENT_AND_CONTEXT`	`void handle(T doc, ChangeStreamContext<T> ctx)`

For @OnChange: only void handle(ChangeStreamContext<T> ctx) is allowed.

Style	Signature
`CONTEXT_ONLY`	`Mono<Void> handle(ChangeStreamContext<T> ctx)`
`DOCUMENT_ONLY`	`Mono<Void> handle(T doc)`
`DOCUMENT_AND_CONTEXT`	`Mono<Void> handle(T doc, ChangeStreamContext<T> ctx)`

For @OnChange: only Mono<Void> handle(ChangeStreamContext<T> ctx) is allowed.

Examples

CONTEXT_ONLY

@OnUpdate
void onUpdate(ChangeStreamContext<Order> ctx) {
    Optional<Order> order = ctx.getFullDocument(Order.class);
    log.info("Order updated: {}", ctx.getDocumentKey());
}

DOCUMENT_ONLY

@OnInsert
void onInsert(Order doc) {
    log.info("New order: {}", doc.getId());
}

DOCUMENT_AND_CONTEXT

@OnInsert
void onInsert(Order doc, ChangeStreamContext<Order> ctx) {
    log.info("Order {} created, attempt #{}", doc.getId(), ctx.getAttemptNumber());
}

Reactive variants

@OnInsert
Mono<Void> onInsertReactive(Order doc, ChangeStreamContext<Order> ctx) {
    return orderService.processReactive(doc);
}

Injecting Other Beans

Need a MongoTemplate, a custom service, or any other Spring bean? Inject it through the handler class (constructor or @Autowired field), not via the handler method signature:

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

    private final MongoTemplate mongoTemplate;
    private final BillingService billing;

    public OrderHandler(MongoTemplate mongoTemplate, BillingService billing) {
        this.mongoTemplate = mongoTemplate;
        this.billing = billing;
    }

    @OnInsert
    void onInsert(Order doc, ChangeStreamContext<Order> ctx) {
        billing.charge(doc);
        mongoTemplate.save(doc, "processed_orders");
    }
}

The handler class is a regular Spring @Component (via @ChangeStream’s meta-annotation), so all standard Spring injection patterns apply.

DELETE handler caveat

For DELETE events, MongoDB does not provide a fullDocument. If you use DOCUMENT_ONLY or DOCUMENT_AND_CONTEXT on @OnDelete, the doc parameter will be null at runtime:

@OnDelete
void onDelete(Order doc, ChangeStreamContext<Order> ctx) {
    // doc is ALWAYS null here
}

Prefer CONTEXT_ONLY for @OnDelete and use ctx.getDocumentKey() to identify the affected document:

@OnDelete
void onDelete(ChangeStreamContext<Order> ctx) {
    log.info("Order deleted: {}", ctx.getDocumentKey());
}

Event Handlers

Dispatch priority, multi-annotation combinations, validation errors.

@ChangeStream

Parent class annotation — documentType, modes, behavior flags.

ChangeStreamContext

The context object passed to every handler.

@Filter

Application-side filtering and signature constraints with @OnDelete.

Annotations

Runtime

SPI

Parameter Styles

Return Types — Mode Exclusivity

Full Signature Matrix

Examples

CONTEXT_ONLY

DOCUMENT_ONLY

DOCUMENT_AND_CONTEXT

Reactive variants

Injecting Other Beans

DELETE handler caveat

See Also

Event Handlers

@ChangeStream

ChangeStreamContext

@Filter

​Parameter Styles

​Return Types — Mode Exclusivity

​Full Signature Matrix

​Examples

​CONTEXT_ONLY

​DOCUMENT_ONLY

​DOCUMENT_AND_CONTEXT

​Reactive variants

​Injecting Other Beans

​DELETE handler caveat

​See Also

Event Handlers

@ChangeStream

ChangeStreamContext

@Filter

Parameter Styles

Return Types — Mode Exclusivity

Full Signature Matrix

Examples

CONTEXT_ONLY

DOCUMENT_ONLY

DOCUMENT_AND_CONTEXT

Reactive variants

Injecting Other Beans

DELETE handler caveat

See Also