liveBook · Manning

Primary port

As explained in Clean Applications with Hexagonal Architecture

An interface exposing an application operation that an external caller can invoke.

When a controller calls a concrete service directly, transport and application behavior can become tangled. A primary port, also called an input port or use-case interface, gives external callers a core-owned contract for an application capability. It describes what the application can do in domain language, without HTTP, messaging, or persistence details. section 2.4.2 section 4.1.1

A primary adapter translates an external trigger into a command or query and invokes the port. A handler inside the core implements the interface, coordinates the use case, delegates business decisions to the domain, and calls output ports when it needs external services. The adapter depends on the contract, not the concrete handler; dependencies point inward. section 2.2 section 4.4.1

Design and enforce the boundary:

  • Name each use-case interface after a business capability, rather than a transport or database technology. Keep the contract focused on the collaboration it represents. section 2.4.2 section 4.1.1
  • Keep commands and queries as input data; the use-case interface names the capability, while its handler supplies behavior. section 9.3.2
  • Make failure part of the signature. Either<Error, Void> preserves a command’s no-data return while making typed success and failure explicit. section 4.8
  • Keep implementations out of the input-ports module. An ArchUnit rule can check that classes in the input-ports package are interfaces. section 9.3 section 7.5.1

Publishing an article

PublishArticleUseCase accepts a PublishArticleCommand. Its handler reads the article through a repository port, delegates publishing to the article, and saves the result. Each step returns an Either, so a failure short-circuits the chain and reaches the caller as a typed error. section 4.1.1 section 4.4.1

Listing 9.10 The input ports: One use case per operation
@UseCase
public interface PublishArticleUseCase extends
  CommandHandler<Error, PublishArticleCommand> { #A
}
 
@UseCase
public interface GetArticleByIdUseCase extends QueryHandler
  <Error, ArticleDTO, GetArticleByIdQuery> { #B
}
 
@UseCase
public interface CreateArticleUseCase extends
  CommandHandler<Error, CreateArticleCommand> { #C
}
 
@UseCase
public interface NotifySubscribersUseCase extends
  CommandHandler<Error, NotifySubscribersCommand> { #D
  }
 
@UseCase
public interface RecordIntegrationEventUseCase extends
  CommandHandler<Error, RecordIntegrationEventCommand> {
}

These interfaces show one named input port per operation, parameterized by its command or query and result type. section 9.3.2

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Develops interface contracts, handler implementation, typed failures, module placement, and automated interface checks.
Examples
Uses article creation and publishing, including a handler that reads, publishes, and saves an article.
What you can do after
Builds use-case interfaces and handlers with explicit typed errors and enforceable port boundaries.
How it connects
Connects hexagonal architecture to primary adapters, application handlers, commands, queries, output ports, and dependency inversion.

Also explained in

Compare how 2 books explain primary port →

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.