public Interface Handler

A Jetty component that handles HTTP requests, of any version (HTTP/1.1, HTTP/2 or HTTP/3). A Handler is a Request.Handler with the addition of LifeCycle behaviours, plus variants that allow organizing Handlers as a tree structure.

Handlers may wrap the Request, Response and/or Callback and then forward the wrapped instances to their children, so that they see a modified request; and/or to intercept the read of the request content; and/or intercept the generation of the response; and/or to intercept the completion of the callback.

A Handler is an Invocable and implementations must respect the InvocationType they declare within calls to handle(Request, Response, Callback).

A minimal tree structure could be:

Server
`- YourCustomHandler

A more sophisticated tree structure:

Server
`- GzipHandler
   `- ContextHandlerCollection
      +- ContextHandler (contextPath="/user")
      |  `- YourUserHandler
      |- ContextHandler (contextPath="/admin")
      |  `- YourAdminHandler
      `- DefaultHandler

A simple Handler implementation could be:

class SimpleHandler extends Handler.Abstract.NonBlocking
{
    @Override
    public boolean handle(Request request, Response response, Callback callback)
    {
        // Implicitly sends a 200 OK response with no content.
        callback.succeeded();
        return true;
    }
}

A more sophisticated example of a Handler that decides whether to handle requests based on their URI path:

class YourHelloHandler extends Handler.Abstract.NonBlocking
{
    @Override
    public boolean handle(Request request, Response response, Callback callback)
    {
        if (request.getHttpURI().getPath().startsWith("/yourPath"))
        {
            // The request is for this Handler
            response.setStatus(200);
            // The callback is completed when the write is completed.
            response.write(true, UTF_8.encode("hello"), callback);
            return true;
        }
        return false;
    }
}

An example of a Handler that decides whether to pass the request to a child:

class ConditionalHandler extends Handler.Wrapper
{
    @Override
    public boolean handle(Request request, Response response, Callback callback)
    {
        if (request.getHttpURI().getPath().startsWith("/yourPath")
            return super.handle(request, response, callback);
        if (request.getHttpURI().getPath().startsWith("/wrong"))
        {
            Response.writeError(request, response, callback, HttpStatus.BAD_REQUEST_400);
            return true;
        }
        return false;
    }
}