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

    • 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

    • 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 type.

    • logMessage

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