liveBook · Manning

Chapter 4: The honest hexagon: Use cases, commands, and the case against exceptions

What you will learn in chapter 4 of Clean Applications with Hexagonal Architecture

Introduces the application layer’s coordinating role and explains why use case contracts should make failure explicit without changing what commands return on success.

After this chapter you will be able to

What it builds on

Section by section

Introduction

Introduces the application layer’s coordinating role and explains why use case contracts should make failure explicit without changing what commands return on success.

Key terms: application layer, domain model, output ports, void, use case contract, exception, Either<Error, R>, typed error, Command-Query Separation (CQS)

4.1 The use case contract

Introduces use cases as the application-layer path for WriteFlow actions and explains how @UseCase marks an input-port interface.

Key terms: use case, application layer, @UseCase, Architecture Kernel, stereotype annotation, input port

4.1.1 Input ports: The hexagon's public API

This section defines input ports as use-case-owned interfaces through which technology-specific adapters drive WriteFlow without depending on handler implementations.

Key terms: input port, input adapter, handler, hexagon boundary, use case, PublishArticleUseCase, PublishArticleCommand, handle, Architecture Kernel, DDD Shared Kernel

4.1.2 The anatomy of a use case

This section explains the sequence of a use case, why it receives validated commands, and why valid input does not guarantee a successful outcome.

Key terms: use case, command, query, domain model, output ports, outcome, PublishArticleCommand, validateThenCreate, handler, application layer

4.2 The incomplete contract

This section shows why a use case signature can correctly return no command data yet still leave its failure contract incomplete.

Key terms: use case, command, void, failure path, exception

4.2.1 The cost of using exceptions for expected failures

The section argues that expected use case failures should be explicit outcomes rather than exceptions, while reserving exceptions for faults that require diagnosis.

Key terms: contingencies, faults, use case contract, unchecked exceptions, checked exceptions, typed outcomes, Either, call stack, control flow, assertThrows

4.2.2 The hidden cost in a hexagonal architecture

This section explains why exception-based failures complicate use-case handlers and why typed return values make their possible outcomes explicit.

Key terms: application layer, handler, repositories, output ports, domain services, try-catch blocks, unchecked exceptions, checked exceptions, method signature, typed return value

4.2.3 A deliberately provocative question

This section argues that use-case signatures should tell input adapters what can go wrong, just as public API contracts do.

Key terms: application layer, input adapters, use cases, void handle(PublishArticleCommand command)

4.3 Either: An honest signature

Introduces Either as an explicit return value for use cases, making success and failure visible in the use case signature.

Key terms: Either<L, R>, left, right, Vavr's Either, Either, DomainError, Void, command, use case contract

4.3.1 What Either says that the void did not

This section shows how an Either return type makes a command’s success and failure outcomes explicit without turning the command into a query.

Key terms: void handle(...), Either<DomainError, Void>, two-branch return value, CQS, Command-Query Separation, outcome signal

4.3.2 The Error hierarchy

This section defines an application-level error taxonomy that distinguishes use case failures while keeping field-level validation details and unexpected exceptions in their proper places.

Key terms: DomainError, Error, input adapters, TechnicalError, exceptions, application boundary, sealed hierarchy, root interface, ValidationErrors, ValidationError

4.3.3 Returning multiple validation failures at once

This subsection updates PublishArticleCommand validation to return all failures using the full Error hierarchy.

Key terms: PublishArticleCommand, Error, validateThenCreate, validation failures

4.3.4 Commands and queries as typed input

This section defines commands and queries as typed, data-only inputs and explains why their behavior lives in handlers instead of the inputs themselves.

Key terms: command, query, typed input, GoF Command, handler, bus, marker interface, Architecture Kernel, ArchUnit

4.4 The Application handler

This section introduces the application handler as the class inside the hexagon that receives a command, coordinates work, and returns an outcome.

Key terms: Application handler, PublishArticleCommand, Either<Error, Void>

4.4.1 From use case interface to handler implementation

This section explains how a handler turns a use case interface into application work and returns a typed outcome through an Either chain.

Key terms: handler, use case interface, repositories, output ports, domain model, Either, typed error, short-circuits, try-catch

4.4.2 Orchestration without business logic leakage

This section explains how a handler orchestrates a use case without taking over validation, business rules, or persistence decisions.

Key terms: handler, orchestration, domain invariant, Article.publish(), validateThenCreate, repository

4.4.3 Cross-cutting concerns at the boundary

This section places cross-cutting concerns at the handler boundary without introducing framework dependencies, and keeps domain objects out of command results.

Key terms: handler, cross-cutting concerns, application core, Architecture Kernel, technology-agnostic annotations, adapter, Either<Error, Void>, domain objects, use case interface, query

4.5 The command bus

This section explains why WriteFlow introduces a command bus and how it dispatches application commands without making adapters depend on individual handlers.

Key terms: use case interface, handler, adapter, injection graph, CommandBus, command, registry, command handler, HTTP router

4.5.1 Why a bus? From one handler to many

This subsection explains how a command bus reduces input-adapter coupling by routing commands to registered handlers.

Key terms: direct injection, input adapter, CommandBus, Open/Closed principle, registry, command type, handler, fail fast

4.5.2 The Command Bus in the Architecture Kernel

Defines the Architecture Kernel’s Either-based command bus contract and shows how a use case joins bus routing without changing its handler implementation.

Key terms: Architecture Kernel, CommandHandler, CommandBus, Either, PublishArticleUseCase, Either<Error, Void>, direct injection, bus routing

4.5.3 Spring wiring: Handlers as beans

This subsection explains how Spring-managed handlers become available to the command bus and how a REST controller uses the bus instead of injecting a use case directly.

Key terms: SpringCommandBus, ApplicationContext, CommandHandler bean, handler registry, REST controller, PublishArticleUseCase, CommandBus, input adapter

4.5.4 Decorating the bus: Logging and metrics

This section shows how command bus decorators add cross-cutting behavior around every command without changing handlers, and distinguishes that role from domain events.

Key terms: CommandBus, Decorator pattern, LoggingCommandBus, decorator chain, dependency injection, decorators, domain events, cross-cutting concerns

4.6 The query bus

This section distinguishes queries from commands and introduces the query side of the bus as a similar structure whose handler returns data.

Key terms: commands, queries, handler, query side

4.6.1 Queries are not commands

This section distinguishes side-effect-free queries from commands and shows how that distinction separates read and write handlers.

Key terms: query, side effects, command handler, query handler, write path, read path, DTO, repository interface

4.6.2 QueryHandler and QueryBus

Introduces the Architecture Kernel’s query-side handler and bus as counterparts to the command-side interfaces.

Key terms: QueryHandler, QueryBus, result type parameter, Architecture Kernel

4.6.3 CQS in practice

Shows how WriteFlow retrieves an article through a separate query path and returns a read-side DTO rather than a domain entity.

Key terms: query, QueryHandler, query bus, use case interface, handler, DTO, Data Transfer Object, projection, aggregate, validateThenCreate

4.7 Domain events: A first look

The section distinguishes publishing an article from the work that follows it and explains why the publishing handler should not own every consequence.

Key terms: primary use case, secondary reactions, handler, state change

4.7.1 When the primary task is done, then what?

This section explains why putting secondary tasks in a handler makes it fragile and difficult to extend.

Key terms: handler, Single Responsibility, Open/Closed, secondary task

4.7.2 Generating events in the domain, publishing in the application layer

This section shows how WriteFlow records a publishing event in the domain, publishes it after saving, and handles secondary reactions in separate listeners.

Key terms: domain event, ArticlePublished, Article aggregate, application handler, output port, queued events, input adapters, listeners, secondary reaction, Open/Close principle

4.7.3 Forward: The full event story

This section distinguishes local domain events from external integration events and explains the limits of synchronous event handling.

Key terms: domain, handler, listener, bounded context, ArticlePublished, domain event, integration event, application layer, synchronous, asynchronous handling

4.8 Summary

Where this is used later

Concepts explained in this chapter

← Chapter 3: Building the domain core Chapter 5: Crossing the boundaries: Adapters, repositories, and the mapping problem →

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.