Package org.axonframework.messaging.commandhandling.gateway

Interface CommandGateway

All Superinterfaces:
DescribableComponent
All Known Implementing Classes:
ConvertingCommandGateway, DefaultCommandGateway
public interface CommandGateway extends DescribableComponent
Interface towards the Command Handling components of an application.

This interface provides a friendlier API toward the CommandBus. The CommandGateway allows for components dispatching commands to wait for the result.

Since:
2.0.0
Author:
Allard Buijze
See Also:

  • Method Details

    • send

      @Nonnull CommandResult send(@Nonnull Object command, @Nonnull Metadata metadata, @Nullable ProcessingContext context)
      Sends the given command with the given metadata in the provided context (if available) and returns a CommandResult immediately, without waiting for the command to execute.

      The caller will therefore not receive any immediate feedback on the command's execution. Instead, hooks can be added to the returned CommandResult to react on success or failure of command execution. A shorthand to retrieve a CompletableFuture is available through the CommandResult.getResultMessage() operation.

      Note that this operation expects the CommandBus to use new threads for command execution.

      The given command and metadata are wrapped as the payload of the CommandMessage that is eventually posted on the CommandBus, unless the command already implements Message. In that case, a CommandMessage is constructed from that message's payload and Metadata. The provided metadata is attached afterward in this case.

      Parameters:
      command - The command payload or CommandMessage to send.
      metadata - Meta-data that must be registered with the command.
      context - The processing context, if any, to dispatch the given command in.
      Returns:
      A command result success and failure hooks can be registered. The CommandResult.getResultMessage() serves as a shorthand to retrieve the response.

    • send

      @Nonnull default CommandResult send(@Nonnull Object command)
      Sends the given command in the provided context (if available) and returns a CommandResult immediately, without waiting for the command to execute.

      The caller will therefore not receive any immediate feedback on the command's execution. Instead, hooks can be added to the returned CommandResult to react on success or failure of command execution. A shorthand to retrieve a CompletableFuture is available through the CommandResult.getResultMessage() operation.

      Note that this operation expects the CommandBus to use new threads for command execution.

      The given command is wrapped as the payload of the CommandMessage that is eventually posted on the CommandBus, unless the command already implements Message. In that case, a CommandMessage is constructed from that message's payload and Metadata.

      Parameters:
      command - The command payload or CommandMessage to send.
      Returns:
      A command result success and failure hooks can be registered. The CommandResult.getResultMessage() serves as a shorthand to retrieve the response.
      See Also:

    • send

      @Nonnull default CommandResult send(@Nonnull Object command, @Nullable ProcessingContext context)
      Sends the given command in the provided context (if available) and returns a CommandResult immediately, without waiting for the command to execute.

      The caller will therefore not receive any immediate feedback on the command's execution. Instead, hooks can be added to the returned CommandResult to react on success or failure of command execution. A shorthand to retrieve a CompletableFuture is available through the CommandResult.getResultMessage() operation.

      Note that this operation expects the CommandBus to use new threads for command execution.

      The given command is wrapped as the payload of the CommandMessage that is eventually posted on the CommandBus, unless the command already implements Message. In that case, a CommandMessage is constructed from that message's payload and Metadata.

      Parameters:
      command - The command payload or CommandMessage to send.
      context - The processing context, if any, to dispatch the given command in.
      Returns:
      A command result success and failure hooks can be registered. The CommandResult.getResultMessage() serves as a shorthand to retrieve the response.
      See Also:

    • send

      @Nonnull default CommandResult send(@Nonnull Object command, @Nonnull Metadata metadata)
      Sends the given command with the given metadata in the provided context (if available) and returns a CommandResult immediately, without waiting for the command to execute.

      The caller will therefore not receive any immediate feedback on the command's execution. Instead, hooks can be added to the returned CommandResult to react on success or failure of command execution. A shorthand to retrieve a CompletableFuture is available through the CommandResult.getResultMessage() operation.

      Note that this operation expects the CommandBus to use new threads for command execution.

      The given command and metadata are wrapped as the payload of the CommandMessage that is eventually posted on the CommandBus, unless the command already implements Message. In that case, a CommandMessage is constructed from that message's payload and Metadata. The provided metadata is attached afterward in this case.

      Parameters:
      command - The command payload or CommandMessage to send.
      metadata - Meta-data that must be registered with the command.
      Returns:
      A command result success and failure hooks can be registered. The CommandResult.getResultMessage() serves as a shorthand to retrieve the response.
      See Also:

    • send

      @Nonnull default <R> CompletableFuture<R> send(@Nonnull Object command, @Nonnull Class<R> resultType)
      Sends the given command and returns a CompletableFuture immediately, without waiting for the command to execute.

      The caller will therefore not receive any immediate feedback on the command's execution. Instead, hooks can be added to the returned CompletableFuture to react on success or failure of command execution.

      Note that this operation expects the CommandBus to use new threads for command execution.

      The given command is wrapped as the payload of the CommandMessage that is eventually posted on the CommandBus, unless the command already implements Message. In that case, a CommandMessage is constructed from that message's payload and Metadata.

      Type Parameters:
      R - The generic type of the expected response.
      Parameters:
      command - The command payload or CommandMessage to send.
      resultType - The class representing the type of the expected command result.
      Returns:
      A CompletableFuture that will be resolved successfully or exceptionally based on the eventual command execution result.
      See Also:

    • send

      @Nonnull default <R> CompletableFuture<R> send(@Nonnull Object command, @Nonnull Class<R> resultType, @Nullable ProcessingContext context)
      Sends the given command and returns a CompletableFuture immediately, without waiting for the command to execute.

      The caller will therefore not receive any immediate feedback on the command's execution. Instead, hooks can be added to the returned CompletableFuture to react on success or failure of command execution.

      Note that this operation expects the CommandBus to use new threads for command execution.

      The given command is wrapped as the payload of the CommandMessage that is eventually posted on the CommandBus, unless the command already implements Message. In that case, a CommandMessage is constructed from that message's payload and Metadata.

      Type Parameters:
      R - The generic type of the expected response.
      Parameters:
      command - The command payload or CommandMessage to send.
      resultType - The class representing the type of the expected command result.
      context - The processing context, if any, to dispatch the given command in.
      Returns:
      A CompletableFuture that will be resolved successfully or exceptionally based on the eventual command execution result.
      See Also:

    • sendAndWait

      @Nullable default Object sendAndWait(@Nonnull Object command)
      Send the given command and waits for completion.

      If the command was successful, its result (if any) is discarded. If it was unsuccessful an exception is thrown. Any checked exceptions that may occur as the result of running the command will be wrapped in a CommandExecutionException.

      If the result is needed, use sendAndWait(Object, Class) instead, as it allows for type conversion of the result payload.

      Parameters:
      command - The command payload or CommandMessage to send.
      Returns:
      The payload of the result message, or null when none is present.
      Throws:
      CommandExecutionException - When a checked exception occurs while handling the command.
      See Also:

    • sendAndWait

      @Nullable default Object sendAndWait(@Nonnull Object command, @Nullable ProcessingContext context)
      Send the given command and waits for completion.

      If the command was successful, its result (if any) is discarded. If it was unsuccessful an exception is thrown. Any checked exceptions that may occur as the result of running the command will be wrapped in a CommandExecutionException.

      If the result is needed, use sendAndWait(Object, Class) instead, as it allows for type conversion of the result payload.

      Parameters:
      command - The command payload or CommandMessage to send.
      context - The processing context, if any, to dispatch the given command in.
      Returns:
      The payload of the result message, or null when none is present.
      Throws:
      CommandExecutionException - When a checked exception occurs while handling the command.
      See Also:

    • sendAndWait

      @Nullable default <R> R sendAndWait(@Nonnull Object command, @Nonnull Class<R> resultType)
      Send the given command and waits for the result converted to the resultType.

      If the command was successful, its result will be converted to the specified returnType and returned. If it was unsuccessful or conversion failed, an exception is thrown. Any checked exceptions that may occur as the result of running the command will be wrapped in a CommandExecutionException.

      Type Parameters:
      R - The generic type of the expected response.
      Parameters:
      command - The command payload or CommandMessage to send.
      resultType - The class representing the type of the expected command result.
      Returns:
      The payload of the result message of type R, or null when none is present.
      Throws:
      CommandExecutionException - When a checked exception occurs while handling the command.
      See Also:

    • sendAndWait

      @Nullable default <R> R sendAndWait(@Nonnull Object command, @Nonnull Class<R> resultType, @Nullable ProcessingContext context)
      Send the given command and waits for the result converted to the resultType.

      If the command was successful, its result will be converted to the specified returnType and returned. If it was unsuccessful or conversion failed, an exception is thrown. Any checked exceptions that may occur as the result of running the command will be wrapped in a CommandExecutionException.

      Type Parameters:
      R - The generic type of the expected response.
      Parameters:
      command - The command payload or CommandMessage to send.
      resultType - The class representing the type of the expected command result.
      context - The processing context, if any, to dispatch the given command in.
      Returns:
      The payload of the result message of type R, or null when none is present.
      Throws:
      CommandExecutionException - When a checked exception occurs while handling the command.