Class LocalHandlerRegistry

java.lang.Object
io.fluxzero.sdk.tracking.handling.LocalHandlerRegistry
All Implemented Interfaces:
HandlerRegistry, HasLocalHandlers
public class LocalHandlerRegistry extends Object implements HandlerRegistry
In-memory implementation of HandlerRegistry that manages and dispatches local message handlers — i.e., handlers that are invoked directly in the publishing thread without involving the Fluxzero Runtime.

The LocalHandlerRegistry only registers and invokes handlers that meet the criteria for local handling. These include:

  • Methods explicitly annotated with LocalHandler
  • Handlers defined inside a message payload class (e.g., query or command) not annotated with TrackSelf

This mechanism is useful for bypassing asynchronous tracking and Fluxzero Runtime involvement when immediate, in-process execution is preferred — such as for fast local queries, synchronous command handlers, or test scenarios.

Self-Handlers

If a message's payload type defines a handler method (e.g., @HandleQuery) and is not marked with TrackSelf, then that handler is considered a "self-handler" and is treated as local. These handlers are lazily constructed by the HandlerFactory and automatically included during message dispatch.

Fallback to Fluxzero Runtime

If no local handlers are found for a given message, it will not be processed in the publishing thread. Instead:
  • The message will be published to the Fluxzero Runtime using the appropriate gateway
  • It will be logged so that remote trackers or consumers can handle it asynchronously

This ensures consistent delivery semantics while giving applications control over what is handled locally.

Thread Safety

Registered handlers are stored in a CopyOnWriteArrayList, making the registry safe for concurrent usage and dynamic handler registration.
See Also:

  • Constructor Details

    • LocalHandlerRegistry

      public LocalHandlerRegistry()

  • Method Details

    • hasLocalHandlers

      public boolean hasLocalHandlers()
      Description copied from interface: HasLocalHandlers
      Indicates whether any local handlers are currently registered for this gateway.
      Specified by:
      hasLocalHandlers in interface HasLocalHandlers
      Returns:
      true if local handlers are present, false otherwise

    • registerHandler

      public Registration registerHandler(Object target, HandlerFilter handlerFilter)
      Description copied from interface: HasLocalHandlers
      Registers a handler object, including only those methods that match the provided HandlerFilter.

      This method offers fine-grained control over which handler methods are registered, based on custom logic applied to method annotations and/or signatures.

      Specified by:
      registerHandler in interface HasLocalHandlers
      Parameters:
      target - the handler object containing annotated methods
      handlerFilter - the filter used to determine which methods should be registered
      Returns:
      a Registration which can be used to unregister the handlers

    • setSelfHandlerFilter

      public void setSelfHandlerFilter(@NonNull @NonNull HandlerFilter selfHandlerFilter)
      Description copied from interface: HasLocalHandlers
      Sets a custom filter to control whether a handler method is considered a local handler for the current application. This is typically used internally to ensure that handlers are associated with the correct application or component.
      Specified by:
      setSelfHandlerFilter in interface HasLocalHandlers
      Parameters:
      selfHandlerFilter - a HandlerFilter to apply to registered handlers

    • handleResult

      public LocalHandlerResult handleResult(DeserializingMessage message)
      Description copied from interface: HandlerRegistry
      Attempts to handle the message locally while preserving a synchronously returned value as a direct value.

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

      Specified by:
      handleResult in interface HandlerRegistry
      Parameters:
      message - the message to dispatch
      Returns:
      the local handling result, including an explicit not-handled result when no handler matches

    • handleResult

      public LocalHandlerResult handleResult(LocalHandlerInput input)
      Description copied from interface: HandlerRegistry
      Attempts to handle a lazy local input.

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

      Specified by:
      handleResult in interface HandlerRegistry
      Parameters:
      input - the local handler input
      Returns:
      the local handling result

    • handleLocal

      public boolean handleLocal(LocalExecution execution)
      Description copied from interface: HandlerRegistry
      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”.

      Specified by:
      handleLocal in interface HandlerRegistry
      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

    • handle

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

    • canHandle

      public boolean canHandle(DeserializingMessage message)
      Description copied from interface: HandlerRegistry
      Returns whether this registry has a local handler that can process the given message.
      Specified by:
      canHandle in interface HandlerRegistry
      Parameters:
      message - the message to inspect
      Returns:
      true if a local handler can handle the message, false otherwise

    • getLocalHandlers

      protected List<Handler<DeserializingMessage>> getLocalHandlers(DeserializingMessage message)
      Returns the full list of handlers that should be used to process the given message.

      This may include a self-handler if the message is a request or schedule type.

    • logMessage

      protected boolean logMessage(HandlerDescriptor invoker)
      Determines whether a handler allows its message to be sent to the Fluxzero Runtime.