liveBook · Manning

Command

As explained in Clean Applications with Hexagonal Architecture

A command object encapsulates data representing a requested application operation.

Passing raw HTTP request fields into application logic couples a use case to its delivery mechanism. A command is a typed input representing an intent to change state. An adapter translates external data into a command, then invokes an input port; the handler coordinates the operation without exposing HTTP or JSON to the core. section 1.3 section 4.3.4

A command carries data, not execution behavior. Unlike the Gang of Four Command pattern, it does not know how to perform the operation: that responsibility belongs to a handler. A query instead requests data. Commands normally return no data on success, but an Either<Error, Void> contract can still make failure explicit. section 4.3.4 section 4.0 section 4.2

Construct commands at the boundary using a private constructor and a static validateThenCreate factory. The factory returns either a valid immutable instance or the collected validation errors. This lets the handler focus on business questions rather than input hygiene. A valid command can still fail during execution, for example when an article does not exist or an author lacks permission. section 4.1.2 section 4.3.3

Publishing an article

PublishArticleCommand carries article and author IDs as strings and a publication date as an Instant. Its factory checks the IDs as UUIDs and requires the date. The handler converts the validated strings into domain value objects, whose factories enforce their own invariants again. Keeping those values out of the command prevents the input-port module and its callers from depending on the domain module. section 9.3.1

Listing 9.8 PublishArticleCommand: A primitive-carrying, self-validating command
@Getter
@Accessors(fluent = true)
@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
public final class PublishArticleCommand
  implements Command { #A
 
  private final String articleId; #B
  private final String authorId;
  private final Instant publicationDate;
 
  public static Either<Error, PublishArticleCommand>
    validateThenCreate(final String articleId,
      final String authorId, final Instant publicationDate) {
    final List<ValidationError> errors =
      new ArrayList<>(); #C
    Validations.validUuid(articleId, "articleId")
      .peekLeft(errors::add);
    Validations.validUuid(authorId, "authorId")
      .peekLeft(errors::add);
    Validations.mandatory(publicationDate, "publicationDate")
      .peekLeft(errors::add);
 
    if (!errors.isEmpty()) {
      return Either.left(new Error.ValidationErrors(
        List.copyOf(errors)));
    }
    return Either.right(new PublishArticleCommand(
      articleId, authorId, publicationDate)); #D
  }
 
}

Inspect the private construction, marker interface, fields, and validation factory of the publish command. section 9.3.1

Make the boundary enforceable:

  • Implement the Command marker interface so the command bus can route the type; use an ArchUnit rule to check command packages. section 7.5.2
  • Check the public static validateThenCreate signature with an architecture rule, but test its behavior separately: valid inputs produce populated instances; invalid inputs produce meaningful errors. section 7.5.3 section 8.3
  • Cover individual null or empty fields and an all-null case where applicable, without testing every possible combination. section 8.3.3

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Works through construction, boundary validation, dispatch requirements, architecture rules, and behavioral tests.
Examples
Uses article creation and publishing commands with author IDs, article IDs, and a publication date.
What you can do after
Builds self-validating commands from scratch and tests their construction and architectural contracts.
How it connects
Connects commands to input ports, handlers, command buses, queries, domain value objects, and explicit error handling.

Also explained in

Compare how 7 books explain command →

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.