org.axonframework.commandhandling.distributed.jgroups
Class JGroupsConnector

java.lang.Object
  org.axonframework.commandhandling.distributed.jgroups.JGroupsConnector

All Implemented Interfaces:

CommandBusConnector

public class JGroupsConnector
extends Object
implements CommandBusConnector

A CommandBusConnector that uses JGroups to discover and connect to other JGroupsConnectors in the network. Depending on the configuration of the channel that was provided, this implementation allows for a dynamic discovery and addition of new members. When members disconnect, their portion of the processing is divided over the remaining members.

This connector uses a consistent hashing algorithm to route commands. This ensures that commands with the same routing key will be sent to the same member, regardless of the sending member of that message.

Members join the CommandBus using a load factor (see connect(int)). This load factor defines the number of sections on the consistent hash ring a node will receive. The more nodes on the ring, the bigger the relative load a member receives. Using a higher number of hashes will also result in a more evenly distribution of load over the different members.

Since:

2.0

Author:

Allard Buijze

Constructor Summary

JGroupsConnector(org.jgroups.JChannel channel, String clusterName, CommandBus localSegment, Serializer serializer)
Initializes the Connector using given resources.

JGroupsConnector(org.jgroups.JChannel channel, String clusterName, CommandBus localSegment, Serializer serializer, HashChangeListener hashChangeListener)
Initializes the Connector using given resources.

Method Summary

boolean	awaitJoined() this method blocks until this member has successfully joined the other members, until the thread is interrupted, or when joining has failed.
boolean	awaitJoined(long timeout, TimeUnit timeUnit) this method blocks until this member has successfully joined the other members, until the thread is interrupted, when the given number of milliseconds have passed, or when joining has failed.
void	connect(int loadFactor) Connects this member to the cluster using the given loadFactor.
ConsistentHash	getConsistentHash() Returns the consistent hash on which current assignment of commands to nodes is being executed.
Set<ConsistentHash.Member>	getMembers() Returns the set of members currently registered with the connector.
String	getNodeName() Returns the name of this node in the cluster, or null if this member is not connected.
void	send(String routingKey, CommandMessage<?> commandMessage) Sends the given command to the node assigned to handle messages with the given routingKey.
<R> void	send(String routingKey, CommandMessage<?> commandMessage, CommandCallback<R> callback) Sends the given command to the node assigned to handle messages with the given routingKey.
<C> void	subscribe(String commandName, CommandHandler<? super C> handler) Subscribe the given handler to commands of type commandType to the local segment of the command bus.
<C> boolean	unsubscribe(String commandName, CommandHandler<? super C> handler) Unsubscribe the given handler to commands of type commandType.

Methods inherited from class java.lang.Object

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

Constructor Detail

JGroupsConnector

public JGroupsConnector(org.jgroups.JChannel channel,
                        String clusterName,
                        CommandBus localSegment,
                        Serializer serializer)

Initializes the Connector using given resources. The channel is used to connect this connector to the other members. The clusterName is the name of the cluster the channel will be connected to. For local dispatching of commands, the given localSegment is used. When messages are remotely dispatched, the given serializer is used to serialize and deserialize the messages.

Note that Connectors on different members need to have the same channel configuration, clusterName and serializer configuration in order to successfully set up a distributed cluster.

Parameters:

channel - The channel (configured, but not connected) used to discover and connect with the other members

clusterName - The name of the cluster to connect to

localSegment - The command bus on which messages with this member as destination are dispatched on

serializer - The serialized used to serialize messages before sending them to other members.

JGroupsConnector

public JGroupsConnector(org.jgroups.JChannel channel,
                        String clusterName,
                        CommandBus localSegment,
                        Serializer serializer,
                        HashChangeListener hashChangeListener)

Initializes the Connector using given resources. The channel is used to connect this connector to the other members. The clusterName is the name of the cluster the channel will be connected to. For local dispatching of commands, the given localSegment is used. When messages are remotely dispatched, the given serializer is used to serialize and deserialize the messages.

Note that Connectors on different members need to have the same channel configuration, clusterName and serializer configuration in order to successfully set up a distributed cluster.

Parameters:

channel - The channel (configured, but not connected) used to discover and connect with the other members

clusterName - The name of the cluster to connect to

localSegment - The command bus on which messages with this member as destination are dispatched on

serializer - The serialized used to serialize messages before sending them to other members.

Method Detail

connect

public void connect(int loadFactor)
             throws ConnectionFailedException

Connects this member to the cluster using the given loadFactor. The loadFactor defines the (approximate) relative load that this member will receive.

A good default value is 100, which will give this member 100 nodes on the distributed hash ring. Giving all members (proportionally) lower values will result in a less evenly distributed hash.

Parameters:

loadFactor - The load factor for this node.

Throws:

ConnectionFailedException - when an error occurs while connecting

awaitJoined

public boolean awaitJoined()
                    throws InterruptedException

this method blocks until this member has successfully joined the other members, until the thread is interrupted, or when joining has failed.

Returns:

true if the member successfully joined, otherwise false.

Throws:

InterruptedException - when the thread is interrupted while joining

awaitJoined

public boolean awaitJoined(long timeout,
                           TimeUnit timeUnit)
                    throws InterruptedException

this method blocks until this member has successfully joined the other members, until the thread is interrupted, when the given number of milliseconds have passed, or when joining has failed.

Parameters:

timeout - The amount of time to wait for the connection to complete

timeUnit - The time unit of the timeout

Returns:

true if the member successfully joined, otherwise false.

Throws:

InterruptedException - when the thread is interrupted while joining

send

public <R> void send(String routingKey,
                     CommandMessage<?> commandMessage,
                     CommandCallback<R> callback)
          throws Exception

Description copied from interface: CommandBusConnector

Sends the given command to the node assigned to handle messages with the given routingKey. The sender expect a reply, and will be notified of the result in the given callback.

If this method throws an exception, the sender is guaranteed that the destination of the command did not receive it. If the method returns normally, the actual implementation of the connector defines the delivery guarantees. Implementations should always invoke the callback with an outcome.

If a member's connection was lost, and the result of the command is unclear, the CommandCallback.onFailure(Throwable) method is invoked with a RemoteCommandHandlingException describing the failed connection. A client may choose to resend a command.

Connectors route the commands based on the given routingKey. Using the same routingKey will result in the command being sent to the same member.

Specified by:

send in interface CommandBusConnector

Type Parameters:

R - The type of object expected as return value in the callback

Parameters:

routingKey - The key describing the routing requirements of this command. Generally, commands with the same routingKey will be sent to the same destination.

commandMessage - The command to send to the (remote) member

callback - The callback on which result notifications are sent

Throws:

Exception - when an error occurs before or during the sending of the message

send

public void send(String routingKey,
                 CommandMessage<?> commandMessage)
          throws Exception

Description copied from interface: CommandBusConnector

Sends the given command to the node assigned to handle messages with the given routingKey. The sender does not expect a reply.

If this method throws an exception, the sender is guaranteed that the destination of the command did not receive it. If the method returns normally, the actual implementation of the connector defines the delivery guarantees.

Connectors route the commands based on the given routingKey. Using the same routingKey will result in the command being sent to the same member. Each message must be sent to exactly one member.

Specified by:

send in interface CommandBusConnector

Parameters:

routingKey - The key describing the routing requirements of this command. Generally, commands with the same routingKey will be sent to the same destination.

commandMessage - The command to send to the (remote) member

Throws:

Exception - when an error occurs before or during the sending of the message

subscribe

public <C> void subscribe(String commandName,
                          CommandHandler<? super C> handler)

Description copied from interface: CommandBusConnector

Subscribe the given handler to commands of type commandType to the local segment of the command bus.

If a subscription already exists for the given type, 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.

Specified by:

subscribe in interface CommandBusConnector

Type Parameters:

C - The Type of command

Parameters:

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

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

unsubscribe

public <C> boolean unsubscribe(String commandName,
                               CommandHandler<? super C> handler)

Description copied from interface: CommandBusConnector

Unsubscribe the given handler to commands of type commandType. If the handler is not currently assigned to that type of command, no action is taken.

Specified by:

unsubscribe in interface CommandBusConnector

Type Parameters:

C - The Type of command

Parameters:

commandName - The name of the command the handler is subscribed to

handler - The handler instance to unsubscribe from the CommandBus

Returns:

true of this handler is successfully unsubscribed, false of the given handler was not the current handler for given commandType.

getConsistentHash

public ConsistentHash getConsistentHash()

Returns the consistent hash on which current assignment of commands to nodes is being executed.

Returns:

the consistent hash on which current assignment of commands to nodes is being executed

getMembers

public Set<ConsistentHash.Member> getMembers()

Returns the set of members currently registered with the connector.

Note that any changes in membership are not reflected in the returned set.

Returns:

the set of members currently registered with the connector

getNodeName

public String getNodeName()

Returns the name of this node in the cluster, or null if this member is not connected.

Returns:

the name of this node in the cluster