When a handler calls a database repository or HTTP client directly, infrastructure decisions can spread into application logic. An outbound port, also called an output port, is a core-owned interface that declares a service the application needs without specifying how to provide it. section 1.1 section 2.3.2
The handler calls the port; a secondary adapter outside the core implements it and performs the infrastructure work. Control flows outward through the port, while implementation dependencies point inward toward the core. An inbound port does the opposite job: it declares what the application offers to callers. section 1.1.1 section 2.2
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 separate article persistence and author lookup from their JPA and external-service adapters. section 1.1.1
Design the contract around the application’s collaboration needs:
- Name the port in domain language, such as ArticleRepository or AuthorLookupOutputPort, not after JPA or REST. section 2.3.2 section 2.4.2
- Choose a collaboration surface rather than a separate port for every database operation. Avoid copying an existing repository’s methods merely because they exist. section 2.4.2 section 2.4.7
- Keep the interface separate from its implementation. In Java, an architectural rule can check that port classes are interfaces and that core code does not depend on adapter or framework types. section 7.5.1 section 2.4.2
Article creation
A handler looks up an author through an output port, validates and creates the article, then saves it through a repository port. It can use an HTTP-backed author adapter or a stub without changing the workflow. section 1.3 section 2.2
Ports can also express event publication or notification delivery. A notification port can accept notification DTOs and return Either<Error, Void>, leaving the delivery channel to its adapter. Event-publishing ports may serve in-process dispatch or write an integration event to an outbox; their failure results represent different boundary failures. section 9.3.4
Listing 9.14 NotificationOutputPort: Deliver via an unspecified channel
@OutputPort
public interface NotificationOutputPort {
Either<Error, Void> notify(final NotificationTextDTO text,
final NotificationTypeDTO type);
}
The notification interface declares the request and typed result without naming a delivery channel. section 9.3.4
In handler tests, mock outbound ports, assert the result, and verify interactions. This tests orchestration without requiring the real external systems; adapters need their own tests for their infrastructure-specific behavior. section 8.8
