liveBook · Manning

Either

As explained in Clean Applications with Hexagonal Architecture

Either is a functional data type representing one of two alternatives, commonly a failure value or a successful result.

A command that returns void says nothing about expected failures. Either makes the outcome part of the use case contract: Either<L, R> holds either a left value, conventionally an error, or a right value representing success. It is a return value, not an exception, and does not unwind the call stack. section 4.0 section 4.3

In a hexagonal application, an input port can declare Either<DomainError, Void> for a command. The right side signals success without returning business data; the left carries a typed failure. A query can instead return Either<Error, R>, with data on the right. Callers still need to handle the returned value deliberately; its type alone does not ensure that they do so. section 4.3 section 4.3.1

Listing 4.10 PublishArticleHandler implementing the use case directly
@ApplicationService #A
@RequiredArgsConstructor
final class PublishArticleHandler implements PublishArticleUseCase {
 
  private final ArticleRepository articleRepository; #B
 
  @Override
  public Either<Error, Void> handle(final PublishArticleCommand command) {
    return this.articleRepository
      .readById(command.articleId()) #C
    .flatMap(article -> article.publish(command.authorId())) #D
    .flatMap(article -> this.articleRepository.save(article)); #E
  }
 
}

The handler composes repository lookup, domain behavior, and persistence with flatMap. A failure short-circuits the remaining steps and returns the error to the caller. section 4.4.1

Keep infrastructure details outside the core. Output ports return outcomes to the handler, and an input adapter translates the final result into its own protocol. For HTTP, a controller can map validation errors to 400 and a missing resource to 404. Expected contingencies are modeled as values; unexpected faults may still require diagnosis. section 1.3 section 2.2 section 4.2.1

Use Validation when independent field checks should report several errors together. A validateThenCreate factory can combine checks, then convert the result to Either for the handler's sequential flow. Either short-circuits on failure, whereas Validation can collect failures before conversion. section 3.3.2

Listing 3.5 Validated creation of an article inside a handler
@ApplicationService
@RequiredArgsConstructor
public class CreateArticleHandler implements CreateArticleUseCase {
  private final ArticleRepository articleRepository;
  private final AuthorOutputPort authorOutputPort;
 
  @Override
  public Either<List<DomainError>, Void>
    handle(final CreateArticleCommand command) {
    return this.authorOutputPort
      .lookupAuthor(command.authorId()) #A
      .flatMap(author -> Article.validateThenCreate( #B
         command.id(), command.title(), command.content(), author.id())
        .mapError(Seq::asJava)
        .toEither()) #C
      .flatMap(this.articleRepository::save);
  }
}

Article creation converts accumulated validation errors to an Either, then saves only if lookup and construction succeed. section 3.3.2

Test the failure path as a returned value: make a repository return a technical error, call the handler, and assert that the result is left and preserves the error. Do not swallow or wrap a persistence error when the contract requires it to propagate. section 8.4.4

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains signatures, flatMap short-circuiting, validation conversion, boundary mapping, and failure testing without detailing Either's implementation internals.
Examples
Uses article publishing and creation handlers, HTTP error responses, and a repository persistence-failure test.
What it assumes
Introduces the validation distinction without requiring functional programming terminology, while expecting familiarity with Java and application architecture.
What you can do after
Apply it via Vavr to compose typed use case outcomes, convert validation results, and test error propagation.
How it connects
Connects functional error handling with hexagonal architecture, command-query separation, validation, and exception handling.

Also explained in

Compare how 6 books explain Either →

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.