Package org.eclipse.jetty.server.handler

Class EventsHandler

java.lang.Object
org.eclipse.jetty.util.component.AbstractLifeCycle
org.eclipse.jetty.util.component.ContainerLifeCycle
org.eclipse.jetty.server.Handler.Abstract
org.eclipse.jetty.server.Handler.AbstractContainer
org.eclipse.jetty.server.Handler.Wrapper
org.eclipse.jetty.server.handler.EventsHandler
All Implemented Interfaces:
Handler, Handler.Container, Handler.Singleton, Request.Handler, Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle, Invocable
Direct Known Subclasses:
LatencyRecordingHandler, StatisticsHandler
public abstract class EventsHandler extends Handler.Wrapper

A Handler.Wrapper that fires events during the processing of the requests.

EventsHandler will emit events for the various phases the server goes through while processing an HTTP request and response.

Subclasses may listen to those events to track timing and/or other values such as request URI, etc.

The events parameters, especially the Request object, may be in a transient state depending on the event, and not all properties/features of the parameters may be available inside a listener method.

It is recommended that the event parameters are not acted upon in the listener methods, or undefined behavior may result. On the other hand, it is legit to store request attributes in one listener method that may be possibly retrieved in another listener method in a later event.

Listener methods are invoked synchronously from the thread that is performing the request processing, and they should not call blocking code (otherwise the request processing will be blocked as well).

The kind of chunk passed to onRequestRead(Request, Content.Chunk) depends on the parent of this handler. For instance, if the parent is the Server, then raw chunks are always passed. If somewhere in the parent chain is the GzipHandler then unzipped chunks are passed.

  • Constructor Details

    • EventsHandler

      public EventsHandler()

    • EventsHandler

      public EventsHandler(Handler handler)

  • Method Details

    • handle

      public boolean handle(Request request, Response response, Callback callback) throws Exception
      Description copied from interface: Request.Handler

      Invoked to handle the passed HTTP request and response.

      The request is accepted by returning true, then handling must be concluded by completing the passed callback. The handling may be asynchronous, i.e. this method may return true and complete the given callback later, possibly from a different thread. If this method returns false, then the callback must not be invoked and any mutation on the response reversed.

      Exceptions thrown by this method may be subsequently handled by an error Request.Handler, if present, otherwise a default HTTP 500 error is generated and the callback completed while writing the error response.

      The simplest implementation is:

       public boolean handle(Request request, Response response, Callback callback)
 {
     callback.succeeded();
     return true;
 }

      A HelloWorld implementation is:

       public boolean handle(Request request, Response response, Callback callback)
 {
     response.write(true, ByteBuffer.wrap("Hello World\n".getBytes(StandardCharsets.UTF_8)), callback);
     return true;
 }
      Specified by:
      handle in interface Request.Handler
      Overrides:
      handle in class Handler.Wrapper
      Parameters:
      request - the HTTP request to handle
      response - the HTTP response to handle
      callback - the callback to complete when the handling is complete
      Returns:
      True if and only if the request will be handled, a response generated and the callback eventually called. This may occur within the scope of the call to this method, or asynchronously some time later. If false is returned, then this method must not generate a response, nor complete the callback.
      Throws:
      Exception - if there is a failure during the handling. Catchers cannot assume that the callback will be called and thus should attempt to complete the request as if a false had been returned.

    • onBeforeHandling

      protected void onBeforeHandling(Request request)
      Invoked just before calling the server handler tree (i.e. just before the Runnable returned from HttpChannel.onRequest(MetaData.Request) is run).

      This is the final state of the request before the handlers are called. This includes any request customization.

      Parameters:
      request - the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
      See Also:

    • onRequestRead

      protected void onRequestRead(Request request, Content.Chunk chunk)
      Invoked every time a request content chunk has been parsed, just before making it available to the application (i.e. from within a call to Request.read()).
      Parameters:
      request - the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
      chunk - a potentially null request content chunk, including error and Trailers chunks. If a reference to the chunk (or its ByteBuffer) is kept, then Retainable.retain() must be called.
      See Also:

    • onAfterHandling

      protected void onAfterHandling(Request request, boolean handled, Throwable failure)
      Invoked after application handling (i.e. just after the call to the Runnable returned from HttpChannel.onRequest(MetaData.Request) returns).
      Parameters:
      request - the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
      handled - if the server handlers handled the request
      failure - the exception thrown by the application
      See Also:

    • onResponseBegin

      protected void onResponseBegin(Request request, int status, HttpFields headers)
      Invoked just before the response is line written to the network (i.e. from within the first call to Response.write(boolean, ByteBuffer, Callback)).
      Parameters:
      request - the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
      status - the response status
      headers - the immutable fields of the response object
      See Also:

    • onResponseWrite

      protected void onResponseWrite(Request request, boolean last, ByteBuffer content)
      Invoked before each response content chunk has been written (i.e. from within the any call to Response.write(boolean, ByteBuffer, Callback)).
      Parameters:
      request - the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
      last - indicating last write
      content - The ByteBuffer of the response content chunk (readonly).
      See Also:

    • onResponseWriteComplete

      protected void onResponseWriteComplete(Request request, Throwable failure)
      Invoked after each response content chunk has been written (i.e. immediately before calling the Callback passed to Response.write(boolean, ByteBuffer, Callback)). This will always fire before onResponseTrailersComplete(Request, HttpFields) is fired.
      Parameters:
      request - the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
      failure - if there was a failure to write the given content
      See Also:

    • onResponseTrailersComplete

      protected void onResponseTrailersComplete(Request request, HttpFields trailers)
      Invoked after the response trailers have been written and the final onResponseWriteComplete(Request, Throwable) event was fired.
      Parameters:
      request - the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
      trailers - the written trailers.

    • onComplete

      @Deprecated protected void onComplete(Request request, Throwable failure)
      Deprecated.
      Override onComplete(Request, int, HttpFields, Throwable) instead.
      Invoked when the request and response processing are complete, just before the request and response will be recycled (i.e. after the Runnable return from HttpChannel.onRequest(MetaData.Request) has returned and the Callback passed to Request.Handler.handle(Request, Response, Callback) has been completed).
      Parameters:
      request - the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
      failure - if there was a failure to complete.

    • onComplete

      protected void onComplete(Request request, int status, HttpFields headers, Throwable failure)
      Invoked when the request and response processing are complete, just before the request and response will be recycled (i.e. after the Runnable return from HttpChannel.onRequest(MetaData.Request) has returned and the Callback passed to Request.Handler.handle(Request, Response, Callback) has been completed).
      Parameters:
      request - the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
      status - the response status.
      headers - the immutable fields of the response object.
      failure - if there was a failure to complete.