[#3485] Add annotated and declarative handler interceptor support for events, commands, and queries

[abuijze]

Summary

Introduces annotated handler interceptor support for all three message types (events, commands, and queries), plus declarative interceptor registration on the command and query module builder APIs.

Annotated interceptors

Three annotations allow interceptor methods to be declared directly on a handling component class:

• @EventHandlerInterceptor — applied before every @EventHandler method on the same instance
• @CommandHandlerInterceptor — applied before every @CommandHandler method on the same instance
• @QueryHandlerInterceptor — applied before every @QueryHandler method on the same instance

Two styles are supported:

Before-interceptor — void method, no chain parameter; chain auto-proceeds after the method returns normally:

@CommandHandlerInterceptor
void audit(CommandMessage<?> command) {
    auditLog.record(command.qualifiedName());
}

Surround-interceptor — returns MessageStream, declares a MessageHandlerInterceptorChain parameter; the method controls whether and when the chain proceeds:

@CommandHandlerInterceptor
MessageStream<?> authorize(CommandMessage<?> command,
                            MessageHandlerInterceptorChain<CommandMessage<?>> chain,
                            ProcessingContext ctx) {
    if (!securityContext.isAuthorized(command)) {
        return MessageStream.failed(new AccessDeniedException("Not authorized"));
    }
    return chain.proceed(command, ctx);
}

The optional payloadType attribute narrows the interceptor to messages whose payload is assignable to a specific type.

The supporting infrastructure (MessageHandlerInterceptorDefinition, ChainedMessageHandlerInterceptorMember, InterceptorChainParameterResolverFactory, LazyMessageStream, IgnoredEntriesMessageStream) is generic and shared across all three message types.

Declarative interceptors

EventHandlingComponentsConfigurer.intercepted(), CommandHandlingModule.CommandHandlerPhase.intercepted(), and QueryHandlingModule.QueryHandlerPhase.intercepted() register a MessageHandlerInterceptor around the component assembled by the module:

CommandHandlingModule.named("orders")
        .commandHandlers()
        .autodetectedCommandHandlingComponent(cfg -> new OrderCommandHandler())
        .intercepted(cfg -> new AuthorizationInterceptor())
        .build();

Multiple calls accumulate interceptors in registration order. The assembled component is wrapped in the appropriate Intercepting*HandlingComponent when at least one interceptor is registered.

Documentation

component-message-intercepting.adoc has been rewritten: the placeholder warning is removed, all three annotation types are documented with correct Axon Framework 5 APIs, and a new section covers the declarative module-level intercepted() approach.

---

This PR resolves #3485.

[abuijze]

Relates to #3485

[smcvb]

I am most doubtful about the use of the payloadType on the annotations. Should we still do that? Furthermore, I see an (I assume) accidental mix of #3485 and #3062 in this PR. I'd expect any @ExceptionHandler logic to be part of the other PR (#4520) that you've created. Lastly, I am missing tests for the @MessageHandlerInterceptor in this renewed setup.

[abuijze]

I removed the payloadType references from the interceptors. It was misleading at best. I decided to not replace it with a messageName or anything, because interceptors are designed to be crosscutting concerns. If they apply to a specific message type, they should be part of that message's handler.
I must have accidentally committed the Exception Handler documentation on the wrong branch. Moved that out from here to #4520, where it belongs.

[sonarqubecloud]

Quality Gate failed

Failed conditions
B Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[smcvb]

My concerns have been addressed, hence I'm approving this pull request.