liveBook · Manning

Command and query bus

As explained in Clean Applications with Hexagonal Architecture

An application component that accepts commands through a uniform interface and dispatches them to corresponding handlers.

As use cases multiply, directly injecting each use case interface can leave adapters with growing constructor dependencies. A command or query bus gives an adapter one interface: it accepts a typed input object, looks up its handler in a registry, and delegates execution. The adapter need not know which handler processes the request. section 4.5 section 4.8

The bus routes application intentions, not HTTP requests. Handlers still orchestrate use cases and delegate business decisions to the domain model. Direct injection remains an option; a bus adds an indirection rather than replacing use case interfaces. section 4.5 section 4.5.2 section 4.8

Listing 4.13 CommandBus from the Architecture Kernel
public interface CommandBus {
  <E, C extends Command> Either<E, Void> 
    execute(final C command); #A
}

The command bus exposes one generic execute method. Its Either result makes failure explicit, while Void indicates that a successful command returns no data. section 4.5.2

A use case can extend CommandHandler for its command type without changing its handler implementation. For a query, the corresponding QueryBus resolves a query handler. Commands and queries can be validated before dispatch, and both flows return explicit Either outcomes. section 4.5.2 section 4.8

Publishing an article

A REST controller validates the article and author identifiers to create a PublishArticleCommand, then calls CommandBus.execute. The bus resolves PublishArticleHandler; the controller folds the outcome into an error response or a no-content response. section 4.5.1 section 4.5.3

Listing 6.5 Command and query bus assembly
@Configuration
class CommandQueryBusAssembler {
 
  @Bean
  CommandBus commandBus(
    final ApplicationContext context) { #A
      return new SpringCommandBus(
        new Registry(context)); #B
  }
 
  @Bean
  QueryBus queryBus(
    final ApplicationContext context) {
      return new SpringQueryBus(
        new Registry(context)); #C
  }
 
}

Spring assembly creates command and query buses with registries backed by the application context. section 6.2.3

At startup, the registry inspects discovered handler beans, resolves their generic message types, and builds an index. At runtime, the bus uses that index rather than scanning the application context again. The registry belongs to assembly infrastructure, not the application core; missing handler registrations should fail fast. section 6.2.3 section 4.5.1

A decorator implements the same bus interface and adds behavior before or after delegation. Chains can apply logging, metrics, validation, tracing, or security context propagation without changing handlers. Use domain events instead for domain-specific consequences of a state change. section 4.5.4

Test the adapter boundary separately: invalid input should return an error without calling the bus, while a bus failure should be delegated to the error handler for response mapping. section 8.5.3

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Defines generic bus contracts and shows handler registration, runtime lookup, Spring assembly, decorators, and failure-path tests.
Examples
Follows article publication through a validated command and demonstrates article retrieval through a query.
What you can do after
Apply it via Spring by registering buses, discovering handler beans, and dispatching validated input from an adapter.
How it connects
Connects input ports, use cases, handlers, registries, decorators, and domain events within hexagonal architecture.

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.