Package org.axonframework.commandhandling.gateway

Interface CommandGateway

All Superinterfaces:
MessageDispatchInterceptorSupport<CommandMessage<?>>
All Known Implementing Classes:
DefaultCommandGateway
public interface CommandGateway extends MessageDispatchInterceptorSupport<CommandMessage<?>>
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

      <C, R> void send(@Nonnull C command, @Nonnull CommandCallback<? super C,? super R> callback)
      Sends the given command, and have the result of the command's execution reported to the given callback.

      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 type of result expected from command execution.
      Parameters:
      command - The command to dispatch.
      callback - The callback to notify when the command has been processed.

    • sendAndWait

      <R> R sendAndWait(@Nonnull Object command)
      Sends the given command and wait for it to execute.

      The result of the execution is returned when available. If the command handling method returns any Object, that Object will be the result from invoking this sendAndWait operation. If the command handling method returns void, that means the result of invoking this operation is null.

      This method will block indefinitely, until a result is available, or until the thread is interrupted. When the thread is interrupted, this method returns null. If command execution resulted in an exception, it is wrapped in a CommandExecutionException. If command dispatching failed, CommandDispatchException is thrown instead.

      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.

      Note that the interrupted flag is set back on the thread if it has been interrupted while waiting.

      Type Parameters:
      R - The type of result expected from command execution.
      Parameters:
      command - The command to dispatch.
      Returns:
      The result of command execution, or null if the thread was interrupted while waiting for the command to execute.
      Throws:
      CommandExecutionException - When an exception occurred while processing the command.
      CommandDispatchException - When an exception occurred while dispatching the command.

    • sendAndWait

      default <R> R sendAndWait(@Nonnull Object command, @Nonnull MetaData metaData)
      Sends the given command with the given metaData and wait for it to execute.

      The result of the execution is returned when available. If the command handling method returns any Object, that Object will be the result from invoking this sendAndWait operation. If the command handling method returns void, that means the result of invoking this operation is null.

      This method will block indefinitely, until a result is available, or until the thread is interrupted. When the thread is interrupted, this method returns null. If command execution resulted in an exception, it is wrapped in a CommandExecutionException. If command dispatching failed, CommandDispatchException is thrown instead.

      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.

      Note that the interrupted flag is set back on the thread if it has been interrupted while waiting.

      Type Parameters:
      R - The type of result expected from command execution.
      Parameters:
      command - The command to dispatch.
      metaData - Meta-data that must be registered with the command.
      Returns:
      The result of command execution, or null if the thread was interrupted while waiting for the command to execute.
      Throws:
      CommandExecutionException - When an exception occurred while processing the command.
      CommandDispatchException - When an exception occurred while dispatching the command.

    • sendAndWait

      <R> R sendAndWait(@Nonnull Object command, long timeout, @Nonnull TimeUnit unit)
      Sends the given command and wait for it to execute.

      The result of the execution is returned when available. If the command handling method returns any Object, that Object will be the result from invoking this sendAndWait operation. If the command handling method returns void, that means the result of invoking this operation is null.

      This method will block until a result is available, or the given timeout was reached, or until the thread is interrupted. When the timeout is reached or the thread is interrupted, this method returns null. If command execution resulted in an exception, it is wrapped in a CommandExecutionException. If command dispatching failed, CommandDispatchException is thrown instead.

      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.

      Note that the interrupted flag is set back on the thread if it has been interrupted while waiting.

      Type Parameters:
      R - The type of result expected from command execution.
      Parameters:
      command - The command to dispatch.
      timeout - The amount of time in the given unit the thread is allowed to wait for the result.
      unit - The unit in which timeout is expressed.
      Returns:
      The result of command execution, or null if the thread was interrupted while waiting for the command to execute.
      Throws:
      CommandExecutionException - When an exception occurred while processing the command.
      CommandDispatchException - When an exception occurred while dispatching the command.

    • sendAndWait

      default <R> R sendAndWait(@Nonnull Object command, @Nonnull MetaData metaData, long timeout, @Nonnull TimeUnit unit)
      Sends the given command with the given metaData and wait for it to execute.

      The result of the execution is returned when available. If the command handling method returns any Object, that Object will be the result from invoking this sendAndWait operation. If the command handling method returns void, that means the result of invoking this operation is null.

      This method will block until a result is available, or the given timeout was reached, or until the thread is interrupted. When the timeout is reached or the thread is interrupted, this method returns null. If command execution resulted in an exception, it is wrapped in a CommandExecutionException. If command dispatching failed, CommandDispatchException is thrown instead.

      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.

      Note that the interrupted flag is set back on the thread if it has been interrupted while waiting.

      Type Parameters:
      R - The type of result expected from command execution.
      Parameters:
      command - The command to dispatch.
      metaData - Meta-data that must be registered with the command.
      timeout - The amount of time in the given unit the thread is allowed to wait for the result.
      unit - The unit in which timeout is expressed.
      Returns:
      The result of command execution, or null if the thread was interrupted while waiting for the command to execute.
      Throws:
      CommandExecutionException - When an exception occurred while processing the command.
      CommandDispatchException - When an exception occurred while dispatching the command.

    • send

      <R> CompletableFuture<R> send(@Nonnull Object command)
      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.

      Parameters:
      command - The command to dispatch.
      Returns:
      A CompletableFuture which will be resolved successfully or exceptionally based on the eventual command execution result.

    • send

      default <R> CompletableFuture<R> send(@Nonnull Object command, @Nonnull MetaData metaData)
      Sends the given command with the given metaData 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 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 to dispatch.
      metaData - Meta-data that must be registered with the command.
      Returns:
      A CompletableFuture which will be resolved successfully or exceptionally based on the eventual command execution result.