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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    REQUEST_TIMEOUT_METADATA_KEY
    Metadata key containing the effective request timeout in milliseconds.

  • 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

  • Field Details

    • REQUEST_TIMEOUT_METADATA_KEY

      static final String REQUEST_TIMEOUT_METADATA_KEY
      Metadata key containing the effective request timeout in milliseconds.

      Request handler implementations set this metadata while dispatching timed requests. Tracking handlers use it to determine whether an indexed request has already expired before invoking the handler.

      See Also:

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

      A non-negative timeout is also written to REQUEST_TIMEOUT_METADATA_KEY so downstream request handlers can recognize stale requests during tracking. A null timeout falls back to this handler's configured default.

      Parameters:
      request - The request message to be sent.
      requestSender - A callback used to dispatch the request.
      timeout - The timeout for this request; null uses the handler default and a negative value disables the 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.

      A non-negative timeout is also written to REQUEST_TIMEOUT_METADATA_KEY on each request so downstream request handlers can recognize stale requests during tracking. A null timeout falls back to this handler's configured default.

      Parameters:
      requests - The requests to send.
      requestSender - A callback used to dispatch the requests.
      timeout - The timeout to apply per request; null uses the handler default and 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