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:

DefaultCommandGateway

Method Summary

Modifier and Type	Method and Description
<C,R> void	send(C command, CommandCallback<? super C,? super R> callback) Sends the given command, and have the result of the command's execution reported to the given callback.
<R> CompletableFuture<R>	send(Object command) Sends the given command and returns a CompletableFuture immediately, without waiting for the command to execute.
default <R> CompletableFuture<R>	send(Object command, MetaData metaData) Sends the given command with the given metaData and returns a CompletableFuture immediately, without waiting for the command to execute.
<R> R	sendAndWait(Object command) Sends the given command and wait for it to execute.
<R> R	sendAndWait(Object command, long timeout, TimeUnit unit) Sends the given command and wait for it to execute.
default <R> R	sendAndWait(Object command, MetaData metaData) Sends the given command with the given metaData and wait for it to execute.
default <R> R	sendAndWait(Object command, MetaData metaData, long timeout, TimeUnit unit) Sends the given command with the given metaData and wait for it to execute.

Methods inherited from interface org.axonframework.messaging.MessageDispatchInterceptorSupport

registerDispatchInterceptor

Method Detail

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.