liveBook · Manning

Transactional annotation

As explained in Clean Applications with Hexagonal Architecture

Spring's @Transactional annotation declares transactional behavior for a class or method.

A use case can load an aggregate, run domain logic, persist changes, and publish events; those steps need one atomic boundary. The Architecture Kernel’s @Transactional annotation declares that intent without importing Spring into the application core. A Spring Boot starter and custom transaction interceptor connect the annotation to Spring’s transaction infrastructure and interpret Either failures for rollback. section 6.3 section 6.6

Place the annotation on the handler that orchestrates the use case—not on repositories, adapters, domain services, or input adapters. That handler defines the atomic unit of work. Using Spring’s own annotation there couples the application core to Spring and makes isolated handler tests depend on Spring’s transaction test infrastructure. section 6.3.4

Set the boundary according to the handler’s role:

  • Query handlers use @Transactional(readOnly = true); a repository write inside the query is rejected at the database level. section 6.3.5
  • Command handlers use @Transactional without the readOnly flag. section 6.3.5

Publishing an article

PublishArticleHandler can load the article, invoke domain behavior, persist the new state, and collect an ArticlePublished event within one transaction. Success commits the state; failure rolls it back. section 6.3.5

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

Use the layer-by-layer placement table to check where the transaction boundary belongs. section 6.3.4

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains handler placement, read-only queries, and the runtime bridge that interprets Either failures for rollback.
Examples
Uses article publication as a command example and a read-only article query handler as a query example.
What it assumes
Assumes handlers orchestrate use cases and return Either rather than throwing exceptions.
What you can do after
Apply it by marking handlers as atomic units and declaring query transactions read-only.
How it connects
Connects transaction boundaries to application handlers, Either, Command Query Separation, and domain events.

Also explained in

Compare how 4 books explain Transactional annotation →

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.