Interface RequestHandler

All Superinterfaces:
AutoCloseable, Namespaced<RequestHandler>
All Known Implementing Classes:
DefaultRequestHandler
public interface RequestHandler extends Namespaced<RequestHandler>, AutoCloseable
Handles the lifecycle of request/response interactions in a Fluxzero client.

A RequestHandler is responsible for sending requests—such as commands, queries, or web requests— and asynchronously completing them when a corresponding response is received. Requests may be handled locally or remotely via the Fluxzero Runtime.

Handling Strategies

  • Local Handling: If a request matches a locally registered handler, the RequestHandler may invoke it directly. The result is either returned immediately or asynchronously via a CompletableFuture.
  • Remote Handling: If the request is dispatched to the Fluxzero Runtime, the handler listens for the corresponding response via a TrackingClient subscribed to the appropriate result log (e.g. result or web response log). Responses are correlated using a unique requestId embedded in each SerializedMessage.

To prevent unnecessary message traffic, the underlying tracker is typically configured with:

  • filterMessageTarget = true, so only messages targeted to this client are delivered.
  • clientControlledIndex = true, allowing precise control over result consumption.

A RequestHandler implementation must ensure lifecycle management, including resource cleanup and deregistration when close() is invoked.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Releases all resources associated with this handler.
    default CompletableFuture<io.fluxzero.common.api.SerializedMessage>
    sendRequest(io.fluxzero.common.api.SerializedMessage request, Consumer<io.fluxzero.common.api.SerializedMessage> requestSender)
    Sends a single request and returns a future that completes when the corresponding response is received.
    CompletableFuture<io.fluxzero.common.api.SerializedMessage>
    sendRequest(io.fluxzero.common.api.SerializedMessage request, Consumer<io.fluxzero.common.api.SerializedMessage> requestSender, Duration timeout)
    Sends a single request with a custom timeout and returns a future for the corresponding response.
    CompletableFuture<io.fluxzero.common.api.SerializedMessage>
    sendRequest(io.fluxzero.common.api.SerializedMessage request, Consumer<io.fluxzero.common.api.SerializedMessage> requestSender, Duration timeout, Consumer<io.fluxzero.common.api.SerializedMessage> intermediateCallback)
     
    default CompletableFuture<io.fluxzero.common.api.SerializedMessage>
    sendRequest(io.fluxzero.common.api.SerializedMessage request, Consumer<io.fluxzero.common.api.SerializedMessage> requestSender, Consumer<io.fluxzero.common.api.SerializedMessage> intermediateCallback)
     
    List<CompletableFuture<io.fluxzero.common.api.SerializedMessage>>
    sendRequests(List<io.fluxzero.common.api.SerializedMessage> requests, Consumer<List<io.fluxzero.common.api.SerializedMessage>> requestSender)
    Sends multiple requests and returns a list of futures for their corresponding responses.
    List<CompletableFuture<io.fluxzero.common.api.SerializedMessage>>
    sendRequests(List<io.fluxzero.common.api.SerializedMessage> requests, Consumer<List<io.fluxzero.common.api.SerializedMessage>> requestSender, Duration timeout)
    Sends multiple requests with a custom timeout and returns a list of futures for their responses.

    Methods inherited from interface Namespaced

    forDefaultNamespace, forNamespace

  • Method Details

    • sendRequest

      default CompletableFuture<io.fluxzero.common.api.SerializedMessage> sendRequest(io.fluxzero.common.api.SerializedMessage request, Consumer<io.fluxzero.common.api.SerializedMessage> requestSender)
      Sends a single request and returns a future that completes when the corresponding response is received.

      The request is assigned a unique requestId and dispatched using the provided sender. The returned CompletableFuture is completed with the result or failed on timeout.

      Parameters:
      request - The request message to be sent.
      requestSender - A callback used to dispatch the request (e.g. to a gateway or transport layer).
      Returns:
      A CompletableFuture that completes with the response message or fails on timeout.

    • sendRequest

      CompletableFuture<io.fluxzero.common.api.SerializedMessage> sendRequest(io.fluxzero.common.api.SerializedMessage request, Consumer<io.fluxzero.common.api.SerializedMessage> requestSender, @Nullable Duration timeout)
      Sends a single request with a custom timeout and returns a future for the corresponding response.
      Parameters:
      request - The request message to be sent.
      requestSender - A callback used to dispatch the request.
      timeout - The timeout for this request. A negative value indicates no timeout.
      Returns:
      A CompletableFuture that completes with the response or fails on timeout.

    • sendRequests

      List<CompletableFuture<io.fluxzero.common.api.SerializedMessage>> sendRequests(List<io.fluxzero.common.api.SerializedMessage> requests, Consumer<List<io.fluxzero.common.api.SerializedMessage>> requestSender)
      Sends multiple requests and returns a list of futures for their corresponding responses.

      Each request is assigned a unique requestId and dispatched using the given sender. The returned list preserves the order of the input requests.

      Parameters:
      requests - The requests to send.
      requestSender - A callback used to dispatch the requests (e.g. batch publisher).
      Returns:
      A list of CompletableFuture instances, one for each request.

    • sendRequests

      List<CompletableFuture<io.fluxzero.common.api.SerializedMessage>> sendRequests(List<io.fluxzero.common.api.SerializedMessage> requests, Consumer<List<io.fluxzero.common.api.SerializedMessage>> requestSender, @Nullable Duration timeout)
      Sends multiple requests with a custom timeout and returns a list of futures for their responses.
      Parameters:
      requests - The requests to send.
      requestSender - A callback used to dispatch the requests.
      timeout - The timeout to apply per request. A negative value disables the timeout.
      Returns:
      A list of CompletableFuture instances, one for each request.

    • sendRequest

      default CompletableFuture<io.fluxzero.common.api.SerializedMessage> sendRequest(io.fluxzero.common.api.SerializedMessage request, Consumer<io.fluxzero.common.api.SerializedMessage> requestSender, Consumer<io.fluxzero.common.api.SerializedMessage> intermediateCallback)

    • sendRequest

      CompletableFuture<io.fluxzero.common.api.SerializedMessage> sendRequest(io.fluxzero.common.api.SerializedMessage request, Consumer<io.fluxzero.common.api.SerializedMessage> requestSender, Duration timeout, Consumer<io.fluxzero.common.api.SerializedMessage> intermediateCallback)

    • close

      void close()
      Releases all resources associated with this handler.

      This typically shuts down any underlying TrackingClient subscriptions, and may cancel or complete any outstanding requests.

      Specified by:
      close in interface AutoCloseable