ServerDispatcher class abstract interface

A generic HTTP request dispatcher in the JetLeaf framework.

The ServerDispatcher interface defines a unified contract for routing and handling HTTP requests in a framework-agnostic way. It abstracts away server-specific logic while providing strongly-typed access to the request (ServerHttpRequest) and response (ServerHttpResponse) objects.

This interface is essential in JetLeaf for implementing modular, reusable, and type-safe request handling pipelines, including routers, middleware, and endpoint controllers.

Overview

An ServerDispatcher is responsible for:

  • Determining whether a request can be handled (canDispatch).
  • Executing business logic, controllers, or downstream handlers (dispatch).
  • Writing responses via the provided ServerHttpResponse and its OutputStream.

Dispatchers may inspect HTTP method, path, headers, query parameters, or custom metadata to decide whether they are responsible for a request.

  • ServerHttpRequest – provides access to request metadata, parameters, headers, attributes, locale, and body content.
  • ServerHttpResponse – provides access to the response object and OutputStream to write response data.
  • OutputStream – used to write bytes, strings, or other payloads to the HTTP response.
  • HttpMethod – standard HTTP verbs such as GET, POST, PUT, DELETE, PATCH.

Dispatch Workflow

  1. Evaluation – The dispatcher evaluates the incoming request via canDispatch. This may involve checking:

    • HTTP method (GET, POST, etc.)
    • HttpRequest path or route pattern
    • Headers or query parameters
    • Custom attributes or context metadata

  2. Handling – If the dispatcher can handle the request, it invokes dispatch, which:

    • Executes the appropriate controller or business logic
    • Writes the response payload using ServerHttpResponse.getOutputStream()
    • Ensures proper flushing and closure of streams

  3. Completion – The dispatcher must ensure the response is complete and the request lifecycle is properly finalized.

Example Usage

class UserDispatcher implements ServerDispatcher {
  @override
  Future<void> dispatch(ServerHttpRequest request, ServerHttpResponse response) async {
    final output = response.getOutputStream();
    final userId = request.getParameter('id') ?? 'unknown';
    await output.writeString('User ID: $userId');
    await output.flush();
    await output.close();
  }
}

final dispatcher = UserDispatcher();
if (dispatcher.canDispatch(request)) {
  await dispatcher.dispatch(request, response);
}

Design Notes

  • The generic parameters <HttpRequest> and <HttpResponse> allow implementations to expose framework-specific request and response types while remaining type-safe.
  • canDispatch should be idempotent and side-effect-free. It is called solely to evaluate request eligibility.
  • dispatch may perform asynchronous operations, including reading request streams, database calls, or network requests.
  • HttpResponse writing should always use the provided OutputStream to ensure consistency and avoid bypassing the framework's lifecycle hooks.
  • Dispatchers can be composed or chained to implement middleware pipelines, prioritizing handlers based on routes, headers, or other criteria.

Common Scenarios

Scenario Method Notes
Route matching canDispatch Evaluates path and HTTP method to see if this dispatcher should handle the request
Executing controller dispatch Runs business logic and writes response via OutputStream
Writing response dispatch Ensures proper encoding, flushing, and closing
Logging / metrics dispatch Can attach request-specific metrics or logs via attributes

See Also

Implementers

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

canDispatch(ServerHttpRequest request) → bool
Determines whether this dispatcher can handle the given request.
dispatch(ServerHttpRequest request, ServerHttpResponse response) → Future<void>
Handles the given request and produces a response.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

THROW_IF_HANDLER_NOT_FOUND_PROPERTY_NAME → const String
The configuration property name that controls whether the web framework should throw an exception when no matching handler is found for an incoming request.