liveBook · Manning

Transaction boundary

As explained in Clean Applications with Hexagonal Architecture

A transaction boundary defines the scope within which a set of operations participates in one atomic transaction.

A use case can lose atomicity when each repository call starts its own transaction: a successful save may be separated from other work that later fails. A transaction boundary defines which operations succeed or fail together. In a hexagonal application, place it on the application service handler, which knows the full scope of the use case. section 6.3.4

Table 6.2 Transaction boundary placement
Layer
@Transactional?
Why
Handler (@ApplicationService )
Yes
Orchestrates the full use case; atomic unit of work
Repository interface
No
Called within the handler's transaction; no independent boundary
Repository adapter
No
Implementation detail; inherits handler's transaction
Domain service
No
Called by the handler; operates within its transaction
Input adapter (e.g. controller)
No
Outside the hexagon; not part of the business transaction

The handler owns the boundary; repositories, adapters, and domain services participate without defining independent use-case boundaries. section 6.3.4

Declare intent with the Architecture Kernel’s technology-agnostic @Transactional annotation, not Spring’s annotation on the handler. A custom transaction interceptor connects that intent to the runtime transaction manager and handles rollback when failure is returned as an Either value rather than thrown as an exception. section 6.3.4 section 6.6

Publishing an article

A publish handler loads the aggregate, invokes its domain behavior, persists the new state, and collects the resulting domain event within one boundary. If the use case fails, the state change rolls back; if it succeeds, the state is committed. section 6.3.5

Command handlers use @Transactional without a read-only flag. Query handlers declare @Transactional(readOnly = true), reinforcing command-query separation by rejecting writes at the database level. section 6.3.5

Event timing affects what the boundary can protect. A synchronous listener participating in the transaction can cause rollback on failure, but external side effects are not necessarily undone. After-commit listeners run only after the primary transaction succeeds. For external integration events, an output port writes to an outbox in the same transaction as the state change; a relay delivers them, and consumers must be idempotent. section 4.7.3 section 6.6

Verify transaction outcomes in focused Spring integration tests, rather than checking only for an annotation. In Spring’s default proxy mode, a call between methods of the same class bypasses the proxy, so the inner method’s annotation does not start a transaction. section 8.7

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains placement, runtime interception, event timing, and focused transaction testing.
Examples
Uses an article publish handler and a read-only article query handler to illustrate transaction declarations.
What you can do after
Operate/configure handler-level transactions and verify their outcomes with focused Spring integration tests.
How it connects
Connects hexagonal architecture, command-query separation, domain events, and the transactional outbox.

Also explained in

Compare how 2 books explain transaction boundary →

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.