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

    • 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(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

    • 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