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<SerializedMessage>	sendRequest(SerializedMessage request, Consumer<SerializedMessage> requestSender)	Sends a single request and returns a future that completes when the corresponding response is received.
CompletableFuture<SerializedMessage>	sendRequest(SerializedMessage request, Consumer<SerializedMessage> requestSender, Duration timeout)	Sends a single request with a custom timeout and returns a future for the corresponding response.
CompletableFuture<SerializedMessage>	sendRequest(SerializedMessage request, Consumer<SerializedMessage> requestSender, Duration timeout, Consumer<SerializedMessage> intermediateCallback)
default CompletableFuture<SerializedMessage>	sendRequest(SerializedMessage request, Consumer<SerializedMessage> requestSender, Consumer<SerializedMessage> intermediateCallback)
List<CompletableFuture<SerializedMessage>>	sendRequests(List<SerializedMessage> requests, Consumer<List<SerializedMessage>> requestSender)	Sends multiple requests and returns a list of futures for their corresponding responses.
List<CompletableFuture<SerializedMessage>>	sendRequests(List<SerializedMessage> requests, Consumer<List<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:

• Constant Field Values

Method Details

sendRequest

default CompletableFuture<SerializedMessage> sendRequest(SerializedMessage request,
 Consumer<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<SerializedMessage> sendRequest(SerializedMessage request,
 Consumer<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<SerializedMessage>> sendRequests(List<SerializedMessage> requests,
 Consumer<List<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<SerializedMessage>> sendRequests(List<SerializedMessage> requests,
 Consumer<List<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<SerializedMessage> sendRequest(SerializedMessage request,
 Consumer<SerializedMessage> requestSender,
 Consumer<SerializedMessage> intermediateCallback)

sendRequest

CompletableFuture<SerializedMessage> sendRequest(SerializedMessage request,
 Consumer<SerializedMessage> requestSender,
 Duration timeout,
 Consumer<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