liveBook · Manning

Application service

As explained in Clean Applications with Hexagonal Architecture

A service that coordinates an application use case and its domain operations without containing infrastructure concerns.

When a request handler mixes HTTP, persistence, and business rules, a change in one concern can reach across the whole use case. An application service keeps that workflow in the core: it implements an input port, coordinates domain operations, and calls output ports without knowing their infrastructure implementations. section 1.3 section 2.2

A controller translates an HTTP request into a command before invoking the input port. The service then works with the command and domain objects; secondary adapters implement its output ports for work such as author lookup and persistence. Callers depend on the use-case interface, not the handler class. section 2.2 section 9.4

Creating an article

CreateArticleHandler looks up an author through an output port, passes the command data and author to Article.validateThenCreate, and saves the resulting entity through a repository port. The chained result stops on an error; the handler does not need to know whether the repository uses PostgreSQL or an in-memory map. section 1.3

Listing 1.3 Orchestration to implement the use case
@Override
public Either<Error, Void> handle(final CreateArticleCommand command) {
  return this.authorOutputPort
➥.lookupAuthor(command.authorId()) // #A
    .flatMap(author -> 
➥ Article.validateThenCreate( // #B
      command.id(), command.title(), command.content(), author).toEither())
    .flatMap(this.articleRepository::save); // #C
}

The handler chains author lookup, validated entity creation, and persistence while returning errors through Either. section 1.3

Keep the service thin: it orchestrates, while domain objects enforce business invariants and adapters handle mechanics. For example, validating a title only in the handler makes every other creation path responsible for remembering the same rule. A domain factory can validate before calling a private constructor, so invalid entities cannot be created through that path. section 3.3.1 section 9.4

The handler is also the transaction boundary for a use case: loading, domain operations, persistence, and event publication may need to succeed or fail together. Use the project's transaction annotation rather than Spring's on the handler, keeping Spring out of the core. A returned Either.left does not automatically trigger Spring rollback; configure the relevant error type when it must abort the transaction. section 6.3.4 section 9.4

Handlers can carry an architecture-kernel @ApplicationService stereotype without depending on Spring APIs. An assembly module configures Spring to discover that stereotype and inject implementations of the interfaces declared in handler constructors; the core does not look up beans. section 6.2.2

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Works through handler orchestration, domain-rule placement, dependency wiring, and transaction boundaries.
Examples
Uses article creation to demonstrate author lookup, validated entity creation, and repository persistence.
What you can do after
Builds a thin use-case handler that coordinates domain operations and ports while keeping infrastructure dependencies outside the core.
How it connects
Connects input ports, output ports, domain entities, adapters, and transaction boundaries.

Also explained in

Compare how 3 books explain application service →

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.