spring-events

Spring Events

Pattern: Process

Conventions for event-driven communication within Spring applications. Targets Framework 7 / Boot 4.0. Most guidance applies to Framework 6.1+ / Boot 3.2+.

Mental model: Events are notifications of something that already happened. The publisher doesn't know or care who listens. Listeners are responsible for their own transactions, idempotency, and failure handling.

Do NOT Load for external messaging (Kafka, RabbitMQ) — use spring-kafka or the appropriate messaging skill. For module-boundary enforcement, combine with spring-modulith.

When to Use

• Publishing domain events within a Spring application
• Choosing between @EventListener, @TransactionalEventListener, and @ApplicationModuleListener
• Debugging why an event listener is not firing
• Configuring async event processing with proper context propagation
• Using the Event Publication Registry for guaranteed delivery

Event Design

Events are immutable records named in past tense — they describe something that happened, not a command:

public record OrderCompleted(String orderId, BigDecimal totalAmount, Instant completedAt) {}

• Include the aggregate ID — listeners need it to look up related data
• Include only data the publisher owns — never query other domains to enrich
• Use value types — String, BigDecimal, Instant, UUID, enums. Never entities or Spring beans
• Keep payloads small — IDs and essential fields. Listeners query their own data if needed

Choosing the Right Listener

Scenario	Annotation	Why
In-memory cache/counter	@EventListener	Synchronous, same transaction. Failure rolls back publisher
Notification after success	@TransactionalEventListener	Only fires after commit
Cross-module side effect	@ApplicationModuleListener	Async, own TX, retry via registry
Derived write before commit	@TransactionalEventListener(BEFORE_COMMIT)	Still in publisher's transaction

Before adding an event listener, ask:

• Should this fail with the publisher? → @EventListener
• Should this only run if the publisher succeeded? → @TransactionalEventListener
• Is this a cross-module concern that needs guaranteed delivery? → @ApplicationModuleListener

Publishing Events

Publish within a @Transactional method, after the state change:

@Transactional
public Order completeOrder(String orderId) {
    var order = orderRepository.findById(orderId).orElseThrow();
    order.complete();
    orderRepository.save(order);
    events.publishEvent(new OrderCompleted(order.getId(), order.getTotalAmount(), Instant.now()));
    return order;
}

Publishing outside a transaction with only @TransactionalEventListener handlers causes silent event loss — no error, no log. Use fallbackExecution = true on the listener if non-transactional publishing is intentional.

Before publishing an event, ask:

• Is there an active @Transactional? Without one, @TransactionalEventListener silently drops the event
• Does the event carry only data the publisher owns? Never query other domains to enrich
• Is the event named in past tense? Events describe what happened, not what should happen

Debugging: Listener Not Firing

Check in this order:

1. No active transaction? — @TransactionalEventListener requires a transaction. Without one, event is silently dropped. Set fallbackExecution = true or ensure @Transactional on publisher
2. @Lazy bean? — listeners on @Lazy beans are never registered. No error at startup
3. Generic type erasure? — @EventListener for EntityCreatedEvent<Person> won't match unless the event implements ResolvableTypeProvider
4. Wrong phase? — AFTER_COMMIT doesn't fire on rollback. Check transaction outcome
5. Exception in earlier listener? — synchronous listeners execute in order; an exception stops subsequent listeners

@EventListener Details

@Order(n) controls synchronous invocation order (lower = first). Without @Order, execution order is undefined. @Order is meaningless for @Async listeners.

Synchronous listeners execute sequentially in the publisher's thread. 10 listeners at 50ms each = 500ms added to the publishing method. Move slow work to @ApplicationModuleListener.

For ordering, conditional listeners (SpEL), return value chaining, and generic event type erasure workarounds, load references/patterns.md.

Async Events

@Async + @TransactionalEventListener

@Async
@TransactionalEventListener
void on(OrderCompleted event) {
    // Runs in separate thread after commit
    // NO transaction context — JPA calls fail or use auto-commit
    // NO context propagation (MDC, tracing) without TaskDecorator
}

Use TaskDecorator (e.g., ContextPropagatingTaskDecorator) on the executor for MDC/tracing propagation. See spring-framework references/scheduling-async.md.

Prefer @ApplicationModuleListener — it wraps @Async + @Transactional(REQUIRES_NEW) + @TransactionalEventListener + registry tracking in one annotation.

ApplicationEventMulticaster

Customizable via a bean named applicationEventMulticaster. Setting a TaskExecutor on it makes ALL events async globally — including Spring's internal events (ContextRefreshedEvent), which causes startup ordering issues. Prefer per-listener @Async instead.

Event Publication Registry (Spring Modulith)

Built-in outbox pattern. Tracks event publications transactionally — failed listeners are retried.

spring:
  modulith:
    events:
      republish-outstanding-events-on-restart: true
      completion-mode: UPDATE              # UPDATE, DELETE, or ARCHIVE
      jdbc:
        schema-initialization:
          enabled: true

Staleness Monitor (Modulith 2.0)

Automatically marks stuck publications as FAILED:

spring:
  modulith:
    events:
      staleness:
        published: PT1H
        processing: PT1H
        check-interval: PT10S

Resubmission (Modulith 2.0)

failedEvents.resubmit(
    ResubmissionOptions.defaults()
        .withBatchSize(100)
        .withMinAge(Duration.ofMinutes(5))
        .withFilter(pub -> pub.getCompletionAttempts() < 3)
);

For full registry configuration, completion modes, saga patterns, and event versioning, load references/patterns.md.

Spring Framework 7

MethodFailureEvent

New event hierarchy for observing method failures:

• MethodRollbackEvent — published by TransactionInterceptor on @Transactional rollback. Listen to centralize rollback logging/alerting
• MethodRetryEvent — published on @Retryable triggered retries

@EventListener
void on(MethodRollbackEvent event) {
    log.warn("Rollback in {}: {}", event.getMethod().getName(), event.getFailure().getMessage());
}

Reactive @TransactionalEventListener

Since Framework 6.1: works with ReactiveTransactionManager. Use TransactionalEventPublisher to include TransactionContext as event source in WebFlux/R2DBC applications.

Testing Events

Test listeners as plain units — inject the event directly. For integration tests:

@Test
void shouldPublishOrderCompleted(AssertablePublishedEvents events) {
    orderService.completeOrder("order-1");
    assertThat(events).contains(OrderCompleted.class)
        .matching(OrderCompleted::orderId, "order-1");
}

Testing gotchas:

• @TransactionalEventListener in @Transactional tests — the test transaction never commits, so AFTER_COMMIT listeners never fire. Use @Commit or test via Spring Modulith's Scenario API
• @ApplicationModuleListener — async + own transaction. Use Scenario.publish(event).andWaitForStateChange(...) to await side effects
• Event Publication Registry — to verify registry entries in tests, inject EventPublicationRepository and assert on publication state

For async/cross-module testing with Spring Modulith's Scenario API, see the spring-modulith skill.

Anti-Patterns

• The Silent Drop — publishing outside @Transactional with only @TransactionalEventListener handlers. Event is silently lost. Use fallbackExecution = true or ensure transactional context
• The Lazy Ghost — @EventListener on a @Lazy bean. Listener is never registered, events never arrive, no error
• The Erased Generic — @EventListener for EntityCreatedEvent<Person> never fires due to type erasure. Implement ResolvableTypeProvider on the event class
• The Thread-Bare Listener — @Async + @TransactionalEventListener without @Transactional(REQUIRES_NEW). Runs with no transaction — JPA calls fail or auto-commit. Use @ApplicationModuleListener
• The Global Async Trap — setting TaskExecutor on ApplicationEventMulticaster makes ALL events async, including Spring internals. Use per-listener @Async instead
• The Swallowed Failure — catching and swallowing exceptions in listeners tracked by the Event Publication Registry. Marks publication as complete when work wasn't done
• The Circular Chain — A publishes event → B listens and publishes → A listens. Synchronous: StackOverflowError. Async: infinite growth. Design event flows as DAGs
• The Slow Publisher — many synchronous listeners adding hidden latency to the publishing method. Move slow work to async listeners

Resource Files

Load on demand for specific topics:

• references/patterns.md — Saga/choreography, compensation, event versioning, idempotent listeners, event enrichment, conditional listening, return value chaining, generic type erasure fix, scheduled resubmission

References

• Spring Framework Events
• Transactional Event Listeners
• Spring Modulith Events