6. Event Processing

The primary responsibility of the ClusterSelector is to, as the name suggests, select a cluster for each Event Listener that subscribes to the Event Bus. By default, all Event Listeners are placed in a single Cluster instance, which dispatches events to its members sequentially and in the calling thread (similar to how the SimpleEventBus works). By providing a custom implementation, you can arrange the Event Listeners into different Cluster instances to suit the requirements of your architecture.

A number of ClusterSelector implementations are available. The ClassNamePrefixClusterSelector, for example, uses a mapping of package prefixes to decide which cluster is (most) suitable for an Event Listener. Similarly, the ClassNamePatternClusterSelector uses pattern matching to decide whether a given cluster is suitable. You can use the CompositeClusterSelector to combine several cluster selectors into a single one.

The Cluster interface describes the behavior of a Cluster. By adding information in the Meta Data of a Cluster, the selector can provide hints to the Terminal about the expected behavior.

The EventBusTerminal forms the bridge between the Clusters inside the Event Bus. While some terminals will dispatch within the same JVM, others are aware of messaging technologies, such as AMQP to dispatch Event Messages to clusters on remote machines. The default implementation dispatches published events to each of the (local) clusters using the publishing thread. This means that with the default terminal, and the default ClusterSelector, the behavior of the ClusteringEventBus is exactly the same as that of the SimpleEventBus.

In a typical AMQP based configuration, the EventBusTerminal would send published events to an Exchange. For each cluster, a Queue would be connected to that exchange. The EventBusTerminal will create a consumer for each cluster, which reads from its related Queue and forwards each message to that cluster. Event Listeners in a distributed environment where at most one instance should receive an Events should be placed in a separate cluster, which competes with the other instances on a single Queue. See Section 6.4, “Distributing the Event Bus” for more information.

By default, all Event Listeners are combined into a single cluster. The order in which the listeners are invoked is undefined. However, when an application defines several clusters, sensible choices need to be made about which Cluster instance to assign to each Event Listener.

As a rule of thumb, Event Listeners that require information managed by another Listener should be in the same cluster. Putting them in the same cluster allows them you to influence the way they are invoked. Once they are assigned to different clusters, this is much harder to do. Furthermore, listeners that may not be replayed, such as ones sending emails, as well as Saga Manager should be placed in a separate cluster. Care should be taken never replay events on a cluster containing this type of Listener.

In some circumstances, it is desirable to ensure a specific handler is invoked before another. To achieve this, some clusters allow an OrderResolver to be configured. The OrderResolver provides an integer value for each given handler, which defines the relative order in which handlers need to be invoked. Listeners for which the resolver provide a lower value are invoked before those with a higher value. The order in which Listeners with the same value are invoked is undefined.

Clusters that have been defined in a Spring context using the <axon:cluster /> element automatically check for Spring's @Order annotation on handler classes. Alternatively, an "order-resolver-ref" attribute can be used to refer to another Order resolver to use.

In some cases, you want to know when a cluster has handled a specific event. For example, when a cluster handles an Event asynchronously, but you need send an acknowledgement to the sender. Generaly, you are unlikely to require this feature directly. It is mainly used by infrastructure components.

The EventProcessingMonitorSupport interface, which was introduced in Axon 2.1, defines class capable of notifying subscribed monitors. Cluster extends this interface, meaning each Cluster implementation must be able to deal with the Event Processing Monitors. Event Listeners that handle Events asynchronously, such as the AsyncAnnotatedSagaManager also implement this interface.

To register a Monitor with a Cluster (or Event Listener), call the subscribeEventProcessingMonitor(...) method. It will be invoked each time an Event has been successfully handled by that listener (by invoking the onEventProcessingCompleted method) or when event handling has failed (by invoking onEventProcessingFailed). A single notification may contain any number of Events.

To make the publication process easier, and safer, Axon provides the EventTemplate class. It is initialized by providing the EventBus instance on which it should publish the events. Optionally, you may also provide meta data which you would like to attach to each event sent through this template. Use the publishEvent(Object) or publishEvent(Object, Map<String,Object)) to publish events. The latter allows you to add meta data to the event, before it is published.

The AnnotationEventListenerAdapter can wrap any object into an event listener. The adapter will invoke the most appropriate event handler method available. These event handler methods must be annotated with the @EventHandler annotation.

The AnnotationEventListenerAdapter, as well as the AbstractAnnotatedAggregateRoot, use ParameterResolvers to resolve the value that should be passed in the parameters of methods annotated with @EventHandler. The AnnotationEventListenerAdapter uses a ParameterResolverFactory to resolve the values for the parameters of the annotated methods. By default, Axon uses a ClasspathParameterResolverFactory, that looks for ParameterResolverFactory instances using the SerivceLoader mechanism.

Axon provides out-of-the-box support for the following parameter types:

You can configure additional ParameterResolvers by implementing the ParameterResolverFactory interface and creating a file named /META-INF/service/org.axonframework.common.annotation.ParameterResolverFactory containing the fully qualified name of the implementing class.

In all circumstances, at most one event handler method is invoked per listener instance. Axon will search the most specific method to invoke, in the following order:

// assume EventB extends EventA 
// and    EventC extends EventB

public class TopListener {

    @EventHandler
    public void handle(EventA event) {
    }

    @EventHandler
    public void handle(EventC event) {
    }
}

public class SubListener extends TopListener {

    @EventHandler
    public void handle(EventB event) {
    }

}

In the example above, the SubListener will receive all instances of EventB as well as EventC (as it extends EventB). In other words, the TopListener will not receive any invocations for EventC at all. Since EventA is not assignable to EventB (it's its superclass), those will be processed by TopListener.

The constructor of the AnnotationEventListenerAdapter takes two parameters: the annotated bean, and optionally a ParameterResolverFactory, which defines how parameters are resolved, defaulting to the mechanism described above. The adapter instance can then be registered to the Event Bus using the subscribe() method on the EventBus.