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 an HTTP Request. However, in two key circumstances the target may differ from the URI of the passed request:

The request and response objects used in the signature of the handle method are ServletRequest and ServletResponse. These are the standard APIs and are moderately restricted in what they can do 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 retrieves the core implementation objects from under any wrappers:

Request base_request = request instanceof Request ? (Request)request : HttpConnection.getCurrentConnection().getHttpChannel().getRequest();
Response base_response = response instanceof Response ? (Response)response : HttpConnection.getCurrentConnection().getHttpChannel().getResponse();

Notice 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 argument indicates the state of the handling of the call and may be:

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

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

You can use the standard servlet response API, which will typically set some status, content headers and then write out the content:

 response.setContentType("text/html");
 response.setStatus(HttpServletResponse.SC_OK);
 response.getWriter().println("<h1>Hello OneHandler</h1>");

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:

 Request base_request = (request instanceof Request) ? (Request)request:HttpConnection.getCurrentConnection().getHttpChannel().getRequest();
 base_request.setHandled(true);

Once the base request or response object is obtained, you can modify it. Typically you would make modifications to accomplish:

You can also update the context of the request:

Typically Jetty passes a modified request to another handler and undoes modifications in a finally block afterwards:

 try
 {
    base_request.setSession(a_session);
    next_handler.handle(target,request,response,dispatch);
 }
 finally
 {
    base_request.setSession(old_session);
 }

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

A handler might 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: