sirius.web.http

Interface WebDispatcher

All Superinterfaces:

sirius.kernel.di.std.Priorized

All Known Implementing Classes:

AssetsDispatcher, ControllerDispatcher, DefaultDispatcher, HelpDispatcher, ServiceDispatcher

public interface WebDispatcher
extends sirius.kernel.di.std.Priorized

Participates in the dispatching process for incoming HTTP requests.

Once a HTTP request is fully read by the server it is dispatched calling all available WebDispatcher instances available. To provide a WebDispatcher, a subclass therefore needs to wear an Register annotation.

As the first request arrives, all dispatchers are asked for their priority (via getPriority() and then sorted according to that in an ascending manner. As default priority PriorityCollector.DEFAULT_PRIORITY can be used. Note that this will only be done once, therefore getPriority() must only return a constant value as it is never re-evaluated. By default, a not found handler (DefaultDispatcher is registered with 999 as priority, so higher priorities will never be executed.

For each incoming request, the list of dispatchers is iterated and dispatch(WebContext) is invoked until one of those returns true, to signal that the request was handled.

The dispatchers are invoked in a separate thread so that blocking operations will not block the web-server itself.

If a dispatcher is willing to handle all incoming data (payload of a PUT or POST request) by itself - instead of just accumulating this data in memory or on disk, the preparePreDispatch(WebContext) method must return an appropriate handler for a given request. This needs to install a ContentHandler. Note that no further dispatch(WebContext) will be called for a request which received a true for its call to preparePreDispatch(WebContext).

Note that preparePreDispatch(WebContext) will be invoked within the event loop of the web-server, therefore absolutely no blocking operations must be performed. However, the returned Callback is executed in its own thread and free of any constraints.

See Also:

WebServerHandler

Field Summary

Fields inherited from interface sirius.kernel.di.std.Priorized

DEFAULT_PRIORITY

Method Summary

Modifier and Type	Method and Description
boolean	dispatch(WebContext ctx) Invoked in order to handle the given request.
default void	dispatch(WebContext ctx, Consumer<WebContext> startOfPipeline, Consumer<WebContext> nextStage) Invoked in order to handle the given request.
int	getPriority() Returns the priority to determine the position in the dispatcher list.
default sirius.kernel.commons.Callback<WebContext>	preparePreDispatch(WebContext ctx) Invoked as soon as the complete request but not its contents are available.

Method Detail

getPriority

int getPriority()

Returns the priority to determine the position in the dispatcher list.

Dispatchers are sorted ascending (lower is better). The default priority is PriorityCollector.DEFAULT_PRIORITY, the max. value is 998 as everything above will be handled by the DefaultDispatcher.

Specified by:

getPriority in interface sirius.kernel.di.std.Priorized

Returns:

the priority of the dispatcher

preparePreDispatch

default sirius.kernel.commons.Callback<WebContext> preparePreDispatch(WebContext ctx)

Invoked as soon as the complete request but not its contents are available.

In contrast to dispatch(WebContext) this method is invoked before the complete data is accumulated. This permits the handler to install an ContentHandler using WebContext.setContentHandler(ContentHandler) in order to directly process the uploaded data. A request for which true was replied will not be dispatched again once it is complete.

Note thatthis method will be invoked within the event loop of the web-server, therefore absolutely no blocking operations must be performed. However, the returned Callback is executed in its own thread and free of any constraints.

Parameters:

ctx - the request to handle

Returns:

the handler which will install the ContentHandler and eventually process the request or null to indicate that no pre-dispatching is possible.

See Also:

ControllerDispatcher.preparePreDispatch(WebContext)

dispatch

default void dispatch(WebContext ctx,
                      Consumer<WebContext> startOfPipeline,
                      Consumer<WebContext> nextStage)
               throws Exception

Invoked in order to handle the given request.

If the dispatcher doesn't feel responsible for handling the request, it simply invokes nextStage.

Note that no blocking operation must be performed in this method. For any complex interaction, a new thread should be forked using Tasks.executor(String). Note that even Response.outputStream(io.netty.handler.codec.http.HttpResponseStatus, String) might block sooner or later to limit heap memory usage - so fork a thread for any serious work besides checking responsibilities for handling requests.

Parameters:

ctx - the request to handle

startOfPipeline - the start of the pipeline in order

nextStage - the next stage to forward the request to in case the dispatcher isn't interested

Throws:

Exception - in case of an error when parsing or dispatching the request

dispatch

boolean dispatch(WebContext ctx)
          throws Exception

Invoked in order to handle the given request.

If the dispatcher doesn't feel responsible for handling the request, it simply returns false. Otherwise if the request is being handled, true must be returned

Note that no blocking operation must be performed in this method. For any complex interaction, a new thread should be forked using Tasks.executor(String). Note that even Response.outputStream(io.netty.handler.codec.http.HttpResponseStatus, String) might block sooner or later to limit heap memory usage - so fork a thread for any serious work besides checking responsibilities for handling requests.

Parameters:

ctx - the request to handle

Returns:

true if the request was handled by this dispatcher, false otherwise.

Throws:

Exception - in case of an error when parsing or dispatching the request