liveBook · Manning

Use case

As explained in Clean Applications with Hexagonal Architecture

A use case is an application operation that coordinates domain rules to accomplish a specific user or system goal.

When business rules spread across controllers and infrastructure, changing a delivery mechanism can force changes throughout the application. A use case gives one application operation a clear boundary: it coordinates a user or system goal, delegates business decisions to the domain model, and uses output ports for external needs. section 1.1 section 4.0

The use case exposes an input port owned by the application core. An HTTP controller, message consumer, or scheduled job translates its trigger into a call to that interface. The port speaks domain language; the adapter depends on the interface, not the concrete handler. section 4.1.1 section 9.3.2

Listing 4.1 PublishArticleUseCase as an input port
@UseCase
public interface PublishArticleUseCase {
    void handle(PublishArticleCommand command);
 

The initial publishing port names one capability and accepts one command. Its void return type does not disclose failure paths. section 4.1.1 section 4.2

A command may correctly return no data, but an exception-only failure path is invisible in its signature. An explicit result such as Vavr's Either<Error, Void> makes failure part of the contract. A query is a separate use case when a caller needs data; returning a domain entity from a command handler would expose internal structure. section 4.0 section 4.2 section 4.4.3

Listing 4.11 Handler with technology-agnostic transactional boundary
@ApplicationService
@RequiredArgsConstructor
@Transactional #A
final class PublishArticleHandler implements PublishArticleUseCase {
 
  private final ArticleRepository articleRepository;
 
  @Override
  public Either<Error, Void> handle(final PublishArticleCommand command) {
    return this.articleRepository.readById(command.articleId())
      .flatMap(article -> article.publish(command.authorId()))
      .flatMap(article -> this.articleRepository.save(article));
  }
 
}

The publishing handler reads an article through an output port, delegates publication to the domain object, and saves the result. Its transaction marker expresses a boundary concern without importing a framework transaction annotation. section 4.4.3

The interface carries the capability and signature; the handler carries the behavior. In a generic handler design, use-case interfaces can extend command or query handler types. Event-triggered operations, such as notifying subscribers, remain ordinary use cases even when no user invokes them directly. section 9.3.2

Keep transaction boundaries, security checks, and logging at the use-case boundary using core-owned abstractions. Runtime implementations belong outside the core. During refactoring, identify domain rules, define ports around existing behavior, and move handlers onto those ports before swapping adapters. section 4.4.3 section 1.1

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Develops input-port contracts and handler orchestration, including explicit failure paths and framework-free cross-cutting boundaries.
Examples
Uses article publication to illustrate a command port, a handler, repository access, and domain delegation.
What you can do after
Builds use-case contracts and handlers from scratch with explicit failure results and framework-free boundaries.
How it connects
Connects input ports and adapters with domain models, output ports, command-query separation, and explicit error handling.

Also explained in

Compare how 8 books explain use case →

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.