Jetty has moved!
Jetty is a project at the Eclipse Foundation.
Jetty Powered:
Contact the core Jetty developers at
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 20 Next »

Writing a Jetty Handler

 The org.mortbay.jetty.Handler interface provides Jetty's core of content generation or manipulation. Classes that implement this interface are used to coordinate requests, filter requests and generate content.

The Handler API

The core API of the Handler interface is

The target

The target of a handler is an identifier for the resource that should handle the passed request. This is normally the URI that is parsed from a HTTP Request. However, in two key circumstances the target may differ from the URI of the passed request:

  1. If the request has been dispatched to a named resource, such as a named servlet, then the target is the name of that resource.
  2. If the request is being made by a call to RequestDispatcher.include(...)
    then the target is the URI of the included resource and will be different to the URI of the actual request.

The Request and Response

The request and response objects used in the signature of the handle method are HttpServletRequest and HttpServletResponse. These are the standard APIs and are moderately restricted in what can be done to the request and response. More often than not, access to the jetty implementations of these classes is required: Request and Response. However, as the request and response may be wrapped by handlers, filters and servlets, it is not possible to pass the implementation directly. The following mantra will retrieve the core implementation objects from under any wrappers:

Note that if the handler passes the request on to another handler, it should use the
request/response objects passed in and not the base objects. This is to preserve any wrapping done by up stream handlers.

The dispatch

The dispatch argument indicates the state of the handling of the call and may be:

  • REQUEST == 1 - An original request received from a connector.
  • FORWARD == 2 - A request being forwarded by a RequestDispatcher
  • INCLUDE == 4 - A request being included by a RequestDispatcher
  • ERROR == 8 - A request being forwarded to a error handler by the container.

These mostly have significance for servlet and related handlers. For example, the security handler only applies authentication and authorization to REQUEST dispatches.

Handling Requests

A Handler may handle a request by:

Generating a Response

The OneHandler embedded example shows how a simple handler may generate a response.

The normal servlet response API may be used and will typically set some status, content headers and the write out the content:

It is also very important that a handler indicate that it has completed handling the request and that the request should not be passed to other handlers:

Filtering the Request and/or Response

Once the base request or response object is obtained, it may be modified. Typically modifications are done to achieve:

  • breaking the URI into contextPath, servletPath and pathInfo components
  • to associate a resource base with a request for static content.
  • to associate a session with a request
  • to associate a security principal with a request
  • to change the URI and paths during a request dispatch forward to another resource.

The context of the request may also be updated:

  • Setting of the current threads context classloader
  • Setting thread locals to identify the current ServletContext.

Typically a modified request is passed to another handler and then the modifications are undone in a finally block afterwards:


The classes that implement the HandlerWrapper class are typically handler filters of this style.

Passing the Request and Response to another handler

A handler may simply inspect the request and use the target, request URI or other information to select another handler to pass the request to. These handlers typically implement the HandlerContainer interface.

Examples include:

A combination of the above.

Other stuff

 Handlers are usually arranged in a list and a request presented to each handler in turn until (or at most) one indicates that the request has been handled. In this situation, this will allow handlers to: 

  • Ignore requests that are not applicable
  • Handle requests by populating the response and/or generating content
  • Modify the request but allow it to pass onto the next handler(s).  Headers and attributes may be modified or an InputStream filter added
  • Modify the response but allow the request to pass onto the next handler(s).  Headers may be modified or OutputStream filters added

These are the handlers that implement the org.mortbay.jetty.Handler interface package:

  • Abstract Handler - Abstract handler.
  • Context Handler - This handler wraps a call to handle by setting the context and servlet path, plus setting the context classloader.
  • Error Handler - Handler for error pages.  It is registered at the org.mortbay.jetty.handler.ErrorHandler context attributed and called by the HttpResponse.sendError method to write an error page.
  • Handler Collection - Handler collection.
  • Default Handler - Handler for resources that were not found.  Implements OPTIONS and TRACE methods for the server.
  • Request Log Handler - This handler can be used to wrap an individual context for context logging.
  • Handler wrapper - Handler collection.

There are some examples of implementing custom handlers in the Embedded Examples.

See also Newbie Guide to Jetty.


  • No labels
Contact the core Jetty developers at
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery