org.axonframework.commandhandling.distributed

Class DistributedCommandBus

java.lang.Object

org.axonframework.commandhandling.distributed.DistributedCommandBus

All Implemented Interfaces:

CommandBus, MessageDispatchInterceptorSupport<CommandMessage<?>>, MessageHandlerInterceptorSupport<CommandMessage<?>>

public class DistributedCommandBus
extends Object
implements CommandBus

Implementation of a CommandBus that is aware of multiple instances of a CommandBus working together to spread load. Each "physical" CommandBus instance is considered a "segment" of a conceptual distributed CommandBus.

The DistributedCommandBus relies on a CommandBusConnector to dispatch commands and replies to different segments of the CommandBus. Depending on the implementation used, each segment may run in a different JVM.

Since:

2.0

Author:

Allard Buijze

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DistributedCommandBus.Builder Builder class to instantiate a DistributedCommandBus.

Field Summary

Fields

Modifier and Type	Field and Description
static int	INITIAL_LOAD_FACTOR The initial load factor of this node when it is registered with the CommandRouter.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DistributedCommandBus(DistributedCommandBus.Builder builder) Instantiate a DistributedCommandBus based on the fields contained in the DistributedCommandBus.Builder.

Method Summary

Modifier and Type	Method and Description
static DistributedCommandBus.Builder	builder() Instantiate a Builder to be able to create a DistributedCommandBus.
<C> void	dispatch(CommandMessage<C> command) Dispatch the given command to the CommandHandler subscribed to the given command's name.
<C,R> void	dispatch(CommandMessage<C> command, CommandCallback<? super C,? super R> callback) Dispatch the given command to the CommandHandler subscribed to the given command's name.
int	getLoadFactor() Returns the current load factor of this node.
Registration	registerDispatchInterceptor(MessageDispatchInterceptor<? super CommandMessage<?>> dispatchInterceptor) Registers the given list of dispatch interceptors to the command bus.
Registration	registerHandlerInterceptor(MessageHandlerInterceptor<? super CommandMessage<?>> handlerInterceptor) Register the given handlerInterceptor.
Registration	subscribe(String commandName, MessageHandler<? super CommandMessage<?>> handler) Subscribe the given handler to commands with the given commandName.
void	updateLoadFactor(int loadFactor) Updates the load factor of this node compared to other nodes registered with the CommandRouter.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INITIAL_LOAD_FACTOR

public static final int INITIAL_LOAD_FACTOR

The initial load factor of this node when it is registered with the CommandRouter.

See Also:

Constant Field Values

Constructor Detail

DistributedCommandBus

protected DistributedCommandBus(DistributedCommandBus.Builder builder)

Instantiate a DistributedCommandBus based on the fields contained in the DistributedCommandBus.Builder.

Will assert that the CommandRouter, CommandBusConnector and MessageMonitor are not null, and will throw an AxonConfigurationException if any of them is null.

Parameters:

builder - the DistributedCommandBus.Builder used to instantiate a DistributedCommandBus instance

Method Detail

builder

public static DistributedCommandBus.Builder builder()

Instantiate a Builder to be able to create a DistributedCommandBus.

The MessageMonitor is defaulted to a NoOpMessageMonitor. The CommandRouter and CommandBusConnector are hard requirements and as such should be provided.

Returns:

a Builder to be able to create a DistributedCommandBus

dispatch

public <C> void dispatch(CommandMessage<C> command)

Description copied from interface: CommandBus

Dispatch the given command to the CommandHandler subscribed to the given command's name. No feedback is given about the status of the dispatching process. Implementations may return immediately after asserting a valid handler is registered for the given command.

Specified by:

dispatch in interface CommandBus

Type Parameters:

C - The payload type of the command to dispatch

Parameters:

command - The Command to dispatch

See Also:

GenericCommandMessage.asCommandMessage(Object)

dispatch

public <C,R> void dispatch(CommandMessage<C> command,
                           CommandCallback<? super C,? super R> callback)

Dispatch the given command to the CommandHandler subscribed to the given command's name. When the command is processed, one of the callback's methods is called, depending on the result of the processing.

When the method returns, the only guarantee provided by the CommandBus implementation is that the command has been successfully received. Implementations are highly recommended to perform basic validation of the command before returning from this method call.

Implementations must start a UnitOfWork when before dispatching the command, and either commit or rollback after a successful or failed execution, respectively.

Specified by:

dispatch in interface CommandBus

Type Parameters:

C - The payload type of the command to dispatch

R - The type of the expected result

Parameters:

command - The Command to dispatch

callback - The callback to invoke when command processing is complete

Throws:

CommandDispatchException - when an error occurs while dispatching the command to a segment

See Also:

GenericCommandMessage.asCommandMessage(Object)

subscribe

public Registration subscribe(String commandName,
                              MessageHandler<? super CommandMessage<?>> handler)

Subscribe the given handler to commands with the given commandName.

If a subscription already exists for the given name, the behavior is undefined. Implementations may throw an Exception to refuse duplicate subscription or alternatively decide whether the existing or new handler gets the subscription.

In the DistributedCommandBus, the handler is subscribed to the local segment only.

Specified by:

subscribe in interface CommandBus

Parameters:

commandName - The name of the command to subscribe the handler to

handler - The handler instance that handles the given type of command

Returns:

a handle to unsubscribe the handler. When unsubscribed it will no longer receive commands.

getLoadFactor

public int getLoadFactor()

Returns the current load factor of this node.

Returns:

the current load factor

updateLoadFactor

public void updateLoadFactor(int loadFactor)

Updates the load factor of this node compared to other nodes registered with the CommandRouter.

Parameters:

loadFactor - the new load factor of this node

registerDispatchInterceptor

public Registration registerDispatchInterceptor(MessageDispatchInterceptor<? super CommandMessage<?>> dispatchInterceptor)

Registers the given list of dispatch interceptors to the command bus. All incoming commands will pass through the interceptors at the given order before the command is dispatched toward the command handler.

Specified by:

registerDispatchInterceptor in interface MessageDispatchInterceptorSupport<CommandMessage<?>>

Parameters:

dispatchInterceptor - The interceptors to invoke when commands are dispatched

Returns:

handle to unregister the interceptor

registerHandlerInterceptor

public Registration registerHandlerInterceptor(MessageHandlerInterceptor<? super CommandMessage<?>> handlerInterceptor)

Description copied from interface: MessageHandlerInterceptorSupport

Register the given handlerInterceptor. After registration, the interceptor will be invoked for each handled Message on the messaging component that it was registered to, prior to invoking the message's handler.

Specified by:

registerHandlerInterceptor in interface MessageHandlerInterceptorSupport<CommandMessage<?>>

Parameters:

handlerInterceptor - The interceptor to register

Returns:

a Registration, which may be used to remove the unregister the interceptor