Handler Enhancers

Handler Enhancers allow you to wrap handlers and add custom logic to the execution or eligibility of handlers for a specific message. Handler enhancers differ from message handler interceptors by the access they provide to the message handling component (e.g., the aggregate member) at the resolution time. Hence, handler enhancers allow for more fine-grained control. You can use handler enhancers to intercept and perform checks on groups of @MessageHandler annotated methods, like a command, event, or query handler.

To create a handler enhancer, you implement the HandlerEnhancerDefinition interface and override the wrapHandler() method. All this method does is give you access to the MessageHandlingMember<T>, which is an object representing any handler specified in the system.

You can then filter these handlers based on the type of Message they handle by using the MessageHandlingMember.canHandleMessageType(Class<? extends Message>) method. Doing so, you can specifically enhance message handlers dealing with, for example, the CommandMessage.

For your handler enhancer to run, you'll need to create a META-INF/services/org.axonframework.messaging.annotation.HandlerEnhancerDefinition file containing the fully qualified class name of the handler enhancer you have created or register the enhancer explicitly in the Configurer. Here's an example of a HandlerEnhancerDefinition that filters messages based on an expected MetaData key and value.

// 1
public class ExampleHandlerDefinition implements HandlerEnhancerDefinition {

    // 2
    @Override
    public <T> MessageHandlingMember<T> wrapHandler(MessageHandlingMember<T> original) {
        return original.attribute("metaDataKey") // 3
                       .map(attr -> new ExampleMessageHandlingMember<>(original))
                       .map(member -> (MessageHandlingMember<T>) member)
                       .orElse(original); // 6
    }

    private static class ExampleMessageHandlingMember<T> extends WrappedMessageHandlingMember<T> {

        private final String metaDataKey;
        private final String expectedValue;

        private ExampleMessageHandlingMember(MessageHandlingMember<T> delegate) {
            super(delegate);
            metaDataKey = (String) delegate.attribute("metaDataKey")
                                           .orElseThrow(() -> new IllegalArgumentException(
                                                   "Missing expected attribute"
                                           ));
            expectedValue = (String) delegate.attribute("expectedValue")
                                             .orElseThrow(() -> new IllegalArgumentException(
                                                     "Missing expected value"
                                             ));
        }

        @Override
        public boolean canHandle(@Nonnull Message<?> message) {
            // 4
            return super.canHandle(message) && expectedValue.equals(message.getMetaData().get(metaDataKey));
        }
    }
}

// ...

// 5
@HasHandlerAttributes
public @interface MyAnnotation {

    String metaDataKey();

    String expectedValue();
}

1. Implement the HandlerEnhancerDefinition interface

2. Override the wrapHandler method to perform your logic.

3. Filter the types of handlers you want to wrap based on a specific attribute, for example, the metaDataKey attribute from the MyAnnotation.

4. Handle the method inside of a MessageHandlingMember. In this case, indicating the handler is only suitable if the meta-data key matches a value.

5. For annotation-specific attributes to exist in the MessageHandlingMember's attribute collection, meta-annotation the custom annotation with HasHandlerAttributes.

6. If you are not interested in wrapping the handler, return the original passed into the wrapHandler method.

To configure your HandlerEnhancerDefintion, you can (1) register it directly with the Configurer or (2) make it a part of the Application Context when you are in a Spring environment.

Axon Configuration API

public class AxonConfig {
    // omitting other configuration methods...
    public void registerExampleHandlerDefinition(Configurer configurer) {
        configurer.registerHandlerEnhancerDefinition(config -> new ExampleHandlerDefinition());
    }
}

Spring Boot AutoConfiguration

@Configuration
public class AxonConfig {
    // omitting other configuration methods...
    @Bean
    public ExampleHandlerDefinition exampleHandlerDefinition() {
        return new ExampleHandlerDefinition();
    }
}