liveBook · Manning

Event handler

As explained in Clean Applications with Hexagonal Architecture

A component that reacts to a published event by invoking additional behavior.

A primary use case becomes difficult to maintain when it directly coordinates every secondary effect. An event handler, or listener, separates one reaction from that operation: it receives a published event and invokes another use case. Each listener has a single responsibility, so adding a reaction need not change the original handler. section 4.7.2

Keep generation, publication, and reaction at separate boundaries. The domain aggregate records an event when a significant state change occurs. After saving the aggregate, the application handler publishes its queued events through an output port. A listener then acts as an input adapter: it translates the event into a command and enters the core through the command bus, rather than calling output ports directly. section 4.7.2 section 6.4.2

Figure 4.5 The domain event flow. The aggregate generates the event. The handler publishes it after the save. An input adapter listens and invokes a new use case. The event exits the hexagon through an output port and re-enters through an input adapter—maintaining the architectural boundary in both directions.

The event leaves the core through an output port and re-enters through a listener as a new use case. section 4.7.2

Execution timing determines failure coupling. Spring delivers events synchronously by default; when a listener participates in the handler’s transaction, its failure can roll back the primary operation. A synchronous external side effect, however, is not necessarily reversible by that transaction. An after-commit listener runs only after a successful commit, so its own failure cannot undo the committed operation. section 4.7.3 section 6.4.2

Listing 6.12 Event listener enters through the bus
@Adapter #A
@RequiredArgsConstructor
final class NotifySubscribersOnArticlePublished {
 
  private final CommandBus commandBus; #B
 
  @TransactionalEventListener(phase = AFTER_COMMIT) #C
  void consume(final ArticlePublished event) {
    NotifySubscribersCommand.validateThenCreate(
      event.articleId().value(),
      event.authorId().value()) #D
    .flatMap(command -> this.commandBus.execute(command))
    .peekLeft(error ->
       log.warn("Notification failed: {}", error)); #E
  }
 
}

The notification listener uses @TransactionalEventListener with AFTER_COMMIT, creates a command from the event, and sends it through the command bus. section 6.4.2

Use synchronous handling when the secondary effect belongs to the same invariant; use after-commit handling for an independent effect. If multiple listeners require an order, Spring’s @Order can specify priority, but ordering may indicate a sequential workflow. An aggregate’s queued event order is only an in-process guarantee for that aggregate, not a broader delivery guarantee. section 6.4.2 section 4.7.2

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains event generation, publication, listener boundaries, transaction timing, and ordering limits; distinguishes local handling from broader delivery concerns.
Examples
Uses article publication to trigger subscriber notifications, statistics, and analytics, with a notification command dispatched through a command bus.
What you can do after
Operate/configure listeners with Spring’s transactional event handling to choose whether secondary failures can roll back the primary operation.
How it connects
Connects domain events to aggregates, input adapters, output ports, command buses, transactions, and bounded contexts.

Also explained in

Compare how 2 books explain event handler →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.