Interface DispatchInterceptor

All Known Implementing Classes:
AdhocDispatchInterceptor, AuthenticatingInterceptor, CorrelatingInterceptor, DataProtectionInterceptor, DisableMetrics, MessageRoutingInterceptor, RecursivePublicationGuard, SchedulingInterceptor, WebResponseCompressingInterceptor, WebsocketResponseInterceptor
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 DispatchInterceptor
Mechanism that enables modification, monitoring, or conditional suppression of messages before they are dispatched to local handlers or published to the Fluxzero Runtime.

A DispatchInterceptor allows observing and transforming messages during the dispatch process. It is typically used to inject metadata, rewrite payloads, log outgoing messages, or prevent dispatching certain messages based on custom rules.

Implementations can also be registered via Java's ServiceLoader. Service-loaded interceptors are picked up automatically by Fluxzero, including when using the TestFixture, and are ordered using @Order.

Key behaviors:

See Also:

  • Field Details

    • defaultInterceptors

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

    • noOp

      static final DispatchInterceptor noOp
      No-op implementation of the DispatchInterceptor that returns the original message unchanged.

  • Method Details

    • interceptDispatch

      Message interceptDispatch(Message message, MessageType messageType, String topic)
      Intercepts the dispatch of a message before it is serialized and published or locally handled.

      You may modify the message or return null to block dispatching. Throwing an exception also prevents dispatching.

      Parameters:
      message - the message to be dispatched
      messageType - the type of the message (e.g., COMMAND, EVENT, etc.)
      topic - the target topic or null if not applicable
      Returns:
      the modified message, the same message, or null to prevent dispatch

    • interceptDispatch

      default Message interceptDispatch(Message message, MessageType messageType, String topic, String namespace)
      Intercepts a dispatch to a specific namespace.

      The default implementation delegates to the namespace-agnostic method so existing interceptors retain their behavior. Interceptors that access namespace-sensitive resources can override this method.

      Parameters:
      message - the message to be dispatched
      messageType - the type of the message
      topic - the target topic or null
      namespace - the target namespace or null for the application namespace
      Returns:
      the modified message, the same message, or null to prevent dispatch

    • interceptLocalDispatch

      default Message interceptLocalDispatch(Message message, MessageType messageType, String topic, String namespace)
      Intercepts a message that may still be handled locally.

      The default delegates to the regular dispatch hook. Interceptors that externalize data may defer that side effect until external publication is certain while keeping the message safe for the remaining interceptor chain.

      Parameters:
      message - the message to be dispatched
      messageType - the type of the message
      topic - the target topic or null
      namespace - the target namespace or null for the application namespace
      Returns:
      the modified message, the same message, or null to prevent dispatch

    • preserveLocalDispatchState

      default void preserveLocalDispatchState(Message previousMessage, Message replacement)
      Carries interceptor-private local dispatch state across a replacement Message.

      The default returns the replacement unchanged. Stateful interceptors may override this without exposing their transient state through message metadata or serialization.

      Parameters:
      previousMessage - the message before another interceptor replaced it
      replacement - the replacement returned by that interceptor, or null when dispatch was suppressed

    • storesLocalDispatchState

      default boolean storesLocalDispatchState()
      Returns whether this interceptor may attach transient state during interceptLocalDispatch(Message, MessageType, String, String).

    • beforeExternalDispatch

      default void beforeExternalDispatch(Message message, MessageType messageType, String topic)
      Completes side effects that were deferred while a message was still eligible for local handling.

      This hook may be called before a local handler whose message will subsequently be published. Implementations should be idempotent because multiple local registries may independently request publication, and should also complete deferred work from modifySerializedMessage(SerializedMessage, Message, MessageType, String) for a direct external fallback.

      Parameters:
      message - the intercepted message
      messageType - the type of the message
      topic - the target topic or null

    • completeLocalDispatch

      default void completeLocalDispatch(Message message)
      Releases transient state retained for a completed local dispatch candidate.
      Parameters:
      message - the final intercepted message

    • withNamespace

      default DispatchInterceptor withNamespace(String namespace)
      Returns a view that supplies the given namespace when callers use the namespace-agnostic dispatch method. Other dispatch hooks continue to delegate to this interceptor.
      Parameters:
      namespace - the namespace to attach to dispatch interception
      Returns:
      a namespace-bound view of this interceptor

    • prepareLocalDispatch

      default PreparedLocalDispatch prepareLocalDispatch(LocalDispatchDescriptor descriptor)
      Prepares this interceptor for repeated local dispatches with the same static message characteristics.

      This optional method lets local handling apply an interceptor without creating a complete Message first. Implementations must preserve the observable behavior of interceptDispatch(Message, MessageType, String). Return null when that is not possible; Fluxzero will then use the regular dispatch path for this payload type.

      The returned policy may be cached and used concurrently. State belonging to a single dispatch must be stored in the supplied LocalExecution, not in the policy itself.

      Parameters:
      descriptor - payload class, message type, and topic shared by the local dispatches
      Returns:
      a thread-safe prepared policy, or null to use regular message-based dispatch

    • modifySerializedMessage

      default SerializedMessage modifySerializedMessage(SerializedMessage serializedMessage, Message message, MessageType messageType, String topic)
      Allows modifications to the serialized representation of the message before it is actually published.

      This is called after interceptDispatch(Message, MessageType, String) and should not be used to block dispatching — use interceptDispatch(Message, MessageType, String) for that purpose instead.

      Parameters:
      serializedMessage - the serialized form of the message
      message - the deserialized message object
      messageType - the message type
      topic - the target topic
      Returns:
      the modified or original SerializedMessage

    • monitorDispatch

      default void monitorDispatch(Message message, MessageType messageType, String topic, String namespace, boolean request)
      Hook to observe the dispatch of a message. This method is called after all interceptors have had a chance to block or modify the message.

      Use this for logging or metrics, but not to alter or block the message.

      Parameters:
      message - the final message about to be handled or published
      messageType - the type of the message
      topic - the topic to which the message is dispatched (can be null)
      namespace - the namespace to which the message is dispatched (can be null)
      request - whether the sender expects a response to this dispatch

    • andThen

      default DispatchInterceptor andThen(DispatchInterceptor nextInterceptor)
      Chains this interceptor with another. The resulting interceptor applies this one first, then the next one.
      Parameters:
      nextInterceptor - the interceptor to run after this one
      Returns:
      a new DispatchInterceptor representing the combined logic