Interface HandlerRegistry

All Superinterfaces:
HasLocalHandlers
All Known Implementing Classes:
HandlerRegistry.MergedHandlerRegistry, HandlerRegistry.NoOpHandlerRegistry, LocalHandlerRegistry
public interface HandlerRegistry extends HasLocalHandlers
Interface for registering and invoking local message handlers.

A HandlerRegistry is responsible for managing one or more message handlers — including discovery, invocation, and filtering logic. It is a central abstraction in scenarios where handlers are registered programmatically (e.g. embedded services, tests, functional configurations).

Responsibilities

  • Registering local handler instances (e.g. beans, stateful components)
  • Dispatching messages to matching handlers
  • Composing multiple registries to form a combined resolution chain
  • Delegating filtering behavior via HandlerFilter

Usage

Handlers can be registered using HasLocalHandlers.registerHandler(Object) or HasLocalHandlers.registerHandler(Object, HandlerFilter). Message handling can be triggered manually via handle(DeserializingMessage). 
HandlerRegistry registry = ...;
registry.registerHandler(new MyCommandHandler());

registry.handle(myMessage).ifPresent(resultFuture -> {
    Object result = resultFuture.join();
    ...
});

Composing Registries

Use andThen(HandlerRegistry) or orThen(HandlerRegistry) to chain multiple registries:
  • andThen: invokes both registries and merges results (e.g. for broadcasting)
  • orThen: invokes the second only if the first produces no result
HandlerRegistry composite = registry1.orThen(registry2);

Built-in Implementations

See Also:

  • Method Details

    • noOp

      static HandlerRegistry noOp()
      A no-op registry that does not register or invoke any handlers.

    • handle

      Optional<CompletableFuture<Object>> handle(DeserializingMessage message)
      Attempts to handle the given message using local handlers.
      Parameters:
      message - the deserialized message to dispatch
      Returns:
      an optional future containing the result, or empty if no handler was found

    • handle

      default Optional<CompletableFuture<Object>> handle(DeserializingMessage message, boolean allowExternalPublication)
      Attempts to handle the message locally while controlling optional SDK-managed external publication.

      The default delegates to handle(DeserializingMessage) because custom registries are assumed to invoke local handlers only. Registries that optionally mirror locally handled messages externally should honor allowExternalPublication.

      Parameters:
      message - the deserialized message to dispatch
      allowExternalPublication - whether SDK-managed mirroring may publish the message externally
      Returns:
      an optional future containing the result, or empty if no handler was found

    • handleResult

      default LocalHandlerResult handleResult(DeserializingMessage message)
      Attempts to handle the message locally while preserving a synchronously returned value as a direct value.

      The default adapts handle(DeserializingMessage) and therefore represents a handled result as a future. Implementations may override this method when they can retain synchronous completion.

      Parameters:
      message - the message to dispatch
      Returns:
      the local handling result, including an explicit not-handled result when no handler matches

    • handleResult

      default LocalHandlerResult handleResult(DeserializingMessage message, boolean allowExternalPublication)
      Attempts to handle the message locally while controlling optional SDK-managed external publication.
      Parameters:
      message - the message to dispatch
      allowExternalPublication - whether SDK-managed mirroring may publish the message externally
      Returns:
      the local handling result

    • handleResult

      default LocalHandlerResult handleResult(LocalHandlerInput input)
      Attempts to handle a lazy local input.

      The default materializes the message and delegates to handleResult(DeserializingMessage). Implementations that support payload-first handling may override this method.

      Parameters:
      input - the local handler input
      Returns:
      the local handling result

    • supportsDeferredExternalization

      default boolean supportsDeferredExternalization()
      Returns whether this registry supports messages whose external-only dispatch side effects are deferred until local handler selection has completed.

      The default is false to preserve the contract of custom registries. Fluxzero's local registry overrides this because its handler and dispatch interceptor chains coordinate deferred externalization.

    • handleLocal

      default boolean handleLocal(LocalExecution execution)
      Attempts payload-first local handling and writes the outcome into the reusable execution frame. Implementations that cannot preserve the lazy input return false, causing the caller to use the canonical message-based path.

      This method is intended for Fluxzero registry implementations. A false result means “use the regular path”, not “no handler exists”.

      Parameters:
      execution - the current local dispatch and destination for its result
      Returns:
      true if this registry completed handler selection on the payload-first path; false to use regular message-based handling

    • canHandle

      default boolean canHandle(DeserializingMessage message)
      Returns whether this registry has a local handler that can process the given message.
      Parameters:
      message - the message to inspect
      Returns:
      true if a local handler can handle the message, false otherwise

    • andThen

      default HandlerRegistry andThen(HandlerRegistry next)
      Creates a composite registry that invokes both this and the given registry.

      Results are merged via thenCombine() if both registries handle the message.

      Parameters:
      next - the registry to invoke second
      Returns:
      a combined registry

    • orThen

      default HandlerRegistry orThen(HandlerRegistry next)
      Creates a fallback registry that only invokes the given registry if this one yields no result.
      Parameters:
      next - the fallback registry
      Returns:
      a combined registry with short-circuiting behavior