JGroups

JGroups is an alternative approach to distributing command bus (commands) besides Axon Server.

The JGroupsConnector uses (as the name already gives away) JGroups as the underlying discovery and dispatching mechanism. Describing the features of JGroups is beyond the scope this reference guide Please refer to the JGroups User Guide for more information.

To use the JGroups components from Axon, make sure the axon-jgroups module is available on the classpath through the preferred dependency management system. When combined with Spring Boot, the axon-jgroups-spring-boot-starter dependency can be included to enable auto-configuration.

Since JGroups handles both discovery of nodes and the communication between them, the JGroupsConnector acts as both a CommandBusConnector and a CommandRouter.

You can find the JGroups specific components for the DistributedCommandBus in the axon-distributed-commandbus-jgroups module.

The JGroupsConnector has four mandatory configuration elements:

channel - which defines the JGroups protocol stack. Generally, a JChannel is constructed with a reference to a JGroups configuration file. JGroups comes with a number of default configurations which can be used as a basis for your own configuration. Do keep in mind that IP Multicast generally doesn’t work in Cloud Services, like Amazon. TCP Gossip is generally a good start in such type of environment.
clusterName - defines the name of the cluster that each segment should register to. Segments with the same cluster name will eventually detect each other and dispatch commands among each other.
localSegment - the Command Bus implementation that dispatches Commands destined for the local JVM. These commands may have been dispatched by instances on other JVMs or from the local one.
serializer - used to serialize command messages before they are sent over the wire.

When using a cache, it should be cleared out when the ConsistentHash changes to avoid potential data corruption (for example, when commands do not specify a @TargetAggregateVersion and a new member quickly joins and leaves the JGroup, modifying the aggregate while it is still cached elsewhere.)

Ultimately, the JGroupsConnector needs to actually connect in order to dispatch messages to other segments. To do so, call the connect() method.

JChannel channel = new JChannel("path/to/channel/config.xml");
CommandBus localSegment = SimpleCommandBus.builder().build();
Serializer serializer = XStreamSerializer.builder().build();

JGroupsConnector connector = JGroupsConnector.builder()
                                             .channel(channel)
                                             .clusterName("myCommandBus")
                                             .localSegment(localSegment)
                                             .serializer(serializer)
                                             .build();
DistributedCommandBus commandBus = DistributedCommandBus.builder()
                                                        .connector(connector)
                                                        .commandRouter(connector)
                                                        .build();

// on one node:
commandBus.subscribe(CommandType.class.getName(), handler);
connector.connect();

// on another node, with more CPU:
commandBus.subscribe(CommandType.class.getName(), handler);
commandBus.subscribe(AnotherCommandType.class.getName(), handler2);
commandBus.updateLoadFactor(150); // defaults to 100
connector.connect();

// from now on, just deal with commandBus as if it is local...

Note that it is not required that all segments have command handlers for the same type of commands. You may use different segments for different command types altogether. The distributed command bus will always choose a node to dispatch a command to that has support for that specific type of command.