Interface HandlerInterceptor

All Superinterfaces:
HandlerDecorator
All Known Implementing Classes:
AuthenticatingInterceptor, ContentFilterInterceptor, DataProtectionInterceptor, DisableMetrics, ErrorReportingInterceptor, HandlerMonitor, SchedulingInterceptor, ValidatingInterceptor
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface HandlerInterceptor extends HandlerDecorator
Intercepts individual message handling operations, enabling cross-cutting behavior around handler invocation.

A HandlerInterceptor can be used to inspect or modify messages before they are passed to a handler, monitor and log handler executions, block certain messages from being handled, or inspect and modify the return value after handling.

Interceptors are typically configured via Consumer.handlerInterceptors(), or applied programmatically using the wrap(Handler) method.

Implementations can also be registered via Java's

invalid reference 
ServiceLoader
. Service-loaded interceptors are picked up automatically by Fluxzero, including when using the TestFixture, and are ordered using @Order.

Common Use Cases:

  • Validating or transforming a message before it reaches the handler
  • Adding logging, tracing, or metrics for observability
  • Conditionally suppressing handler invocation
  • Decorating or modifying the result of a handler method

Example:

public class LoggingHandlerInterceptor implements HandlerInterceptor {
    @Override
    public Function<DeserializingMessage, Object> interceptHandling(
            Function<DeserializingMessage, Object> next, HandlerInvoker invoker) {
        return message -> {
            log.info("Before handling: {}", message.getPayload());
            Object result = next.apply(message);
            log.info("After handling: {}", result);
            return result;
        };
    }
}
See Also:

  • Field Details

    • defaultInterceptors

      static final List<HandlerInterceptor> defaultInterceptors
      Default handler interceptors discovered via Java's service loader, sorted by Order. These interceptors are applied automatically by Fluxzero.

  • Method Details

    • interceptHandling

      Function<DeserializingMessage, Object> interceptHandling(Function<DeserializingMessage, Object> function, HandlerInvoker invoker)
      Intercepts the message handling logic.

      The function parameter represents the next step in the handling chain— typically the actual message handler. The invoker provides metadata and invocation logic for the underlying handler method.

      Within this method, an interceptor may:

      • Modify the DeserializingMessage before passing it to the handler
      • Bypass the handler entirely and return a value directly
      • Wrap the result after the handler is invoked

      Note: Interceptors may return a different DeserializingMessage, but it must be compatible with a handler method in the same target class. If no suitable handler is found, an exception will be thrown.

      Parameters:
      function - the next step in the handler chain (typically the handler itself)
      invoker - the metadata and execution strategy for the actual handler method
      Returns:
      a decorated function that wraps handling behavior

    • prepare

      default HandlerInterceptor.PreparedHandlerInterceptor prepare(HandlerDescriptor handler)
      Prepares this interceptor for a specific handler method.

      The returned interceptor is cached and reused concurrently for invocations with the same stable handler metadata. Implementations may use this hook to resolve annotation- or signature-based policy once while keeping message-dependent decisions inside HandlerInterceptor.PreparedHandlerInterceptor.interceptHandling(DeserializingMessage, HandlerDescriptor, BiFunction, HandlerInterceptor.PreparedHandlerFunction).

      The default adapter preserves the existing interceptHandling(Function, HandlerInvoker) contract and deliberately disables the reusable HandlerMethod path. Custom interceptors therefore retain their current behavior unless they explicitly opt into preparation.

      Parameters:
      handler - stable metadata for the handler method
      Returns:
      a thread-safe prepared interceptor

    • prepareInput

      default HandlerInterceptor.PreparedHandlerInputInterceptor prepareInput(HandlerDescriptor handler)
      Prepares this interceptor to run without first creating a complete message.

      Return null when the interceptor requires the regular message-based handling path. The default only supports an interceptor whose prepared behavior is the shared no-op policy, so existing interceptors retain their exact behavior unless they opt in explicitly.

      The returned policy may be cached and invoked concurrently.

      Parameters:
      handler - stable information about the selected handler method
      Returns:
      a thread-safe payload-first policy, or null to use regular message-based handling

    • prepareInput

      default HandlerInterceptor.PreparedHandlerInputInterceptor prepareInput(HandlerDescriptor handler, HandlerInput<DeserializingMessage> input)
      Prepares this interceptor using both the selected handler method and a representative input.

      Override this overload when the interceptor's ability to use payload-first handling depends on input characteristics. The default delegates to prepareInput(HandlerDescriptor).

      Parameters:
      handler - stable information about the selected handler method
      input - a representative input for the prepared handler plan
      Returns:
      a thread-safe payload-first policy, or null to use regular message-based handling

    • supportsPreparation

      default boolean supportsPreparation()
      Indicates whether this interceptor opts into the prepared, mergeable handler wrapper.

      The default is false, preserving the exact wrapper behavior of existing custom interceptors. An interceptor should return true only when prepare(HandlerDescriptor) returns a thread-safe plan that fully represents its handling behavior. If a subclass overrides only the legacy interceptHandling(Function, HandlerInvoker) method, the legacy wrapper is retained automatically.

      Returns:
      true when this interceptor may be merged into a prepared wrapper

    • wrap

      default Handler<DeserializingMessage> wrap(Handler<DeserializingMessage> handler)
      Wraps a Handler with this interceptor, producing an intercepted handler.
      Specified by:
      wrap in interface HandlerDecorator
      Parameters:
      handler - the original handler to wrap
      Returns:
      an intercepted handler that applies this interceptor to all handled messages