Module org.eclipse.jetty.server

Package org.eclipse.jetty.server

Interface Handler

All Superinterfaces:

org.eclipse.jetty.util.component.Destroyable, org.eclipse.jetty.util.thread.Invocable, org.eclipse.jetty.util.component.LifeCycle, Request.Handler

All Known Subinterfaces:

Handler.Collection, Handler.Container, Handler.Singleton, HandlerContainer

All Known Implementing Classes:

AbstractHandler, AbstractHandlerContainer, BufferedResponseHandler, ConnectHandler, ContextHandler, ContextHandlerCollection, DebugHandler, DefaultHandler, DelayedHandler, EventsHandler, GracefulHandler, GzipHandler, Handler.Abstract, Handler.Abstract.NonBlocking, Handler.AbstractContainer, Handler.Sequence, Handler.Wrapper, HotSwapHandler, IdleTimeoutHandler, InetAccessHandler, LatencyRecordingHandler, MovedContextHandler, PathMappingsHandler, ProxiedRequestHandler, ResourceHandler, ResourceHandler.ResourceContext, SecuredRedirectHandler, Server, ShutdownHandler, SizeLimitHandler, StatisticsHandler, StatisticsHandler.MinimumDataRateHandler, ThreadLimitHandler, TryPathsHandler

@ManagedObject("Handler")
public interface Handler
extends org.eclipse.jetty.util.component.LifeCycle, org.eclipse.jetty.util.component.Destroyable, Request.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 Invocable.InvocationType they declare within calls to Request.Handler.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;
     }
 }
 

See Also:

• Request.Handler

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Handler.Abstract	An abstract implementation of Handler that is a ContainerLifeCycle.
static class	Handler.AbstractContainer	A Handler.Abstract that implements Handler.Container.
static interface	Handler.Collection	A Handler.Container that can contain multiple other Handlers.
static interface	Handler.Container	A Handler that contains one or more other Handlers.
static class	Handler.Sequence	A Handler.Container that contains an ordered list of children Handlers whose Request.Handler.handle(Request, Response, Callback) method is invoked in sequence on each child until a child returns true.
static interface	Handler.Singleton	A Handler.Container that can contain one single other Handler.
static class	Handler.Wrapper	An implementation of Handler.Singleton, which is a Handler.Container that wraps one single other Handler.

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.thread.Invocable

org.eclipse.jetty.util.thread.Invocable.Callable, org.eclipse.jetty.util.thread.Invocable.InvocationType, org.eclipse.jetty.util.thread.Invocable.ReadyTask, org.eclipse.jetty.util.thread.Invocable.Task

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

org.eclipse.jetty.util.component.LifeCycle.Listener

Field Summary

Fields inherited from interface org.eclipse.jetty.util.thread.Invocable

__nonBlocking, NOOP

Method Summary

Modifier and Type	Method	Description
Server	getServer()
void	setServer(Server server)

Methods inherited from interface org.eclipse.jetty.util.component.Destroyable

destroy

Methods inherited from interface org.eclipse.jetty.util.thread.Invocable

getInvocationType

Methods inherited from interface org.eclipse.jetty.util.component.LifeCycle

addEventListener, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeEventListener, start, stop

Methods inherited from interface org.eclipse.jetty.server.Request.Handler

handle

Method Details

getServer

@ManagedAttribute(value="the Server instance associated to this Handler",
                  readonly=true)
Server getServer()

Returns:

the Server associated with this Handler

setServer

void setServer(Server server)

Parameters:

server - the Server to associate to this Handler