Package org.eclipse.jetty.server.handler

Class StateTrackingHandler

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.StateTrackingHandler
All Implemented Interfaces:
Handler, Handler.Container, Handler.Singleton, Request.Handler, Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle, Invocable
@ManagedObject public class StateTrackingHandler extends Handler.Wrapper

A troubleshooting Handler.Wrapper that tracks whether Handler/Request/Response asynchronous APIs are properly used by applications.

The violation of these tracked APIs are reported to a StateTrackingHandler.Listener instance; the default listener implementation emits warning logs.

StateTrackingHandler can be linked in at any point in the Handler chain, and even be present in multiple instances, likely configured differently.

For example, to troubleshoot wrong usages of the callback passed to method handle(Request, Response, Callback), a StateTrackingHandler should be configured as the outermost Handler. This is because the handle(...) call propagates inwards. In this way, StateTrackingHandler can wrap the callback passed to inner Handlers and verify that it is eventually completed.

On the other hand, to troubleshoot custom Handler implementations that perform wrapping of Response.write(boolean, ByteBuffer, Callback), a StateTrackingHandler should be configured after the custom Handler implementation. This is because the write(...) call propagates outwards. In this way, StateTrackingHandler can wrap the write(...) call before forwarding it to outer Handlers and eventually to the Jetty implementation, and verify that it is eventually completed.

See Also:

  • Constructor Details

  • Method Details

    • getHandlerCallbackTimeout

      @ManagedAttribute("The timeout in ms for the completion of the handle() callback") public long getHandlerCallbackTimeout()
      Returns:
      the timeout in ms for the completion of the handle(Request, Response, Callback) callback

    • setHandlerCallbackTimeout

      public void setHandlerCallbackTimeout(long timeout)

    • isCompleteHandlerCallbackAtTimeout

      @ManagedAttribute("Whether the handle() callback is completed in case of timeout") public boolean isCompleteHandlerCallbackAtTimeout()
      Returns:
      whether the handle(Request, Response, Callback) callback is completed in case the getHandlerCallbackTimeout() expires
      See Also:

    • setCompleteHandlerCallbackAtTimeout

      public void setCompleteHandlerCallbackAtTimeout(boolean completeHandlerCallbackAtTimeout)

    • getDemandCallbackTimeout

      @ManagedAttribute("The timeout in ms for the execution of the demand callback") public long getDemandCallbackTimeout()
      Returns:
      the timeout in ms for the execution of the demand callback passed to Request.demand(Runnable)

    • setDemandCallbackTimeout

      public void setDemandCallbackTimeout(long timeout)

    • getWriteTimeout

      @ManagedAttribute("The timeout in ms for the execution of a response write") public long getWriteTimeout()
      Returns:
      the timeout in ms for the execution of a Response.write(boolean, ByteBuffer, Callback) call

    • setWriteTimeout

      public void setWriteTimeout(long timeout)

    • getWriteCallbackTimeout

      @ManagedAttribute("The timeout in ms for the execution of the response write callback") public long getWriteCallbackTimeout()
      Returns:
      the timeout in ms for the execution of the response write callback passed to Response.write(boolean, ByteBuffer, Callback)

    • setWriteCallbackTimeout

      public void setWriteCallbackTimeout(long timeout)

    • handle

      public boolean handle(Request originalRequest, Response originalResponse, Callback originalCallback) 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:
      originalRequest - the HTTP request to handle
      originalResponse - the HTTP response to handle
      originalCallback - 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.
      See Also:

    • dump

      public void dump(Appendable out, String indent) throws IOException
      Description copied from interface: Dumpable
      Dump this object (and children) into an Appendable using the provided indent after any new lines. The indent should not be applied to the first object dumped.
      Specified by:
      dump in interface Dumpable
      Overrides:
      dump in class ContainerLifeCycle
      Parameters:
      out - The appendable to dump to
      indent - The indent to apply after any new lines.
      Throws:
      IOException - if unable to write to Appendable

    • toString

      public String toString()
      Overrides:
      toString in class AbstractLifeCycle