liveBook · Manning

Driven adapter

As explained in Clean Applications with Hexagonal Architecture

An adapter that implements an output port and translates application requests into interactions with an external system.

When a handler calls a database or external API directly, infrastructure choices spread into business logic. A driven adapter, also called an output or secondary adapter, keeps those details outside the application core. The core defines an output port for what it needs; the adapter implements that port and translates the request into an interaction with an external system. section 1.1 section 5.2.1

Control flows outward when the handler calls the port, but source dependencies point inward: both the handler and the adapter depend on the core-owned interface. A driving adapter works in the opposite direction of interaction, receiving an external request and invoking an input port. section 1.1.1 section 2.2

Keep the boundary explicit:

  • Name the port for the core’s need, such as ArticleRepository or AuthorLookupOutputPort, rather than for a technology such as JPA or REST. section 2.3.2
  • Put queries, API calls, serialization, data mapping, and infrastructure-error translation in the adapter. Keep business decisions and domain invariants in the handler or domain. section 2.3.2 section 5.2.1
  • Inject the concrete adapter at assembly time. Replacing it with an in-memory implementation or another infrastructure implementation should not require changes inside the core. section 5.2 section 5.2.1

Saving an article

CreateArticleHandler depends on the ArticleRepository interface and calls save after validating and creating an Article. JpaArticleRepositoryAdapter implements the interface and hides the JPA details. An in-memory repository can fulfill the same port for development or tests. section 1.1.1 section 1.3

Listing 1.1 Relating these pieces in code
public interface CreateArticleUseCase {  // #A
    Either<Error, Void> execute(CreateArticleCommand command);
}
 
public interface ArticleRepository {
    Either<Error, Void> save(Article article); // #B
}
 
public interface GetAuthorBiblioOutputPort { // #C
    Either<Error, BiblioDTO> biblioForAuthor(String author);
}
 
public class CreateArticleHandler implements
➥ CreateArticleUseCase { // #D
    private final ArticleRepository repository;
    // ... orchestration logic
}
public class JpaArticleRepositoryAdapter 
➥ implements ArticleRepository { // #E
    // ... JPA/database details hidden here
}
 
public class AuthorBiblioAdapter implements 
➥ GetAuthorBiblioOutputPort { // #F
    // ... call external API/service
}
 

The interfaces, handler, and concrete adapters show which classes own the contracts and which implement them. section 1.1.1

Calling an author service

An outbound adapter implements an author-validation port, calls the service’s published API, and maps its response into the port’s DTO. It also maps failures into local errors, such as AuthorNotFound or DependencyUnavailable. The handler sees the local contract, not the service’s model. section 11.4

For synchronous calls, bound the wait and retry only transient failures. Retry an ambiguous state-changing call only if the contract guarantees deduplication for the same idempotency key or an authoritative check confirms the first attempt had no effect; otherwise reconcile the uncertain outcome. Boundary checks can also enforce inward dependencies and catch infrastructure leakage. section 11.9 section 9.5

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains adapter responsibilities, dependency direction, model and error translation, assembly, and synchronous-call safeguards.
Examples
Uses a JPA article repository, an in-memory repository, and an author-service adapter to illustrate driven adapters.
What you can do after
Build it from scratch by implementing a core-owned port, translating infrastructure interactions, and wiring the adapter at assembly time.
How it connects
Connects driven adapters to output ports, dependency inversion, repositories, anti-corruption layers, and hexagonal architecture.

Also explained in

Compare how 3 books explain driven adapter →

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.