Module org.eclipse.jetty.server

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, org.eclipse.jetty.util.component.Container, org.eclipse.jetty.util.component.Destroyable, org.eclipse.jetty.util.component.Dumpable, org.eclipse.jetty.util.component.Dumpable.DumpableContainer, org.eclipse.jetty.util.component.LifeCycle, org.eclipse.jetty.util.thread.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:

• StateTrackingHandler.Listener

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	StateTrackingHandler.Listener	Listener of events emitted by StateTrackingHandler.
static class	StateTrackingHandler.ThreadInfo

Nested classes/interfaces inherited from class org.eclipse.jetty.server.Handler.Abstract

Handler.Abstract.NonBlocking

Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

org.eclipse.jetty.util.component.AbstractLifeCycle.AbstractLifeCycleListener, org.eclipse.jetty.util.component.AbstractLifeCycle.StopException

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

org.eclipse.jetty.util.component.Container.InheritedListener

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

org.eclipse.jetty.util.component.Dumpable.DumpableContainer

Nested classes/interfaces inherited from interface org.eclipse.jetty.server.Handler

Handler.Abstract, Handler.AbstractContainer, Handler.Collection, Handler.Container, Handler.Sequence, Handler.Singleton, Handler.Wrapper

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.server.Request.Handler

Request.Handler.AbortException

Field Summary

Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

FAILED, STARTED, STARTING, STOPPED, STOPPING

Fields inherited from interface org.eclipse.jetty.util.component.Dumpable

KEY

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

__nonBlocking, NOOP

Constructor Summary

Constructors

Constructor	Description
StateTrackingHandler()	Creates a new instance with a default StateTrackingHandler.Listener that logs events at warning level.
StateTrackingHandler(StateTrackingHandler.Listener listener)	Creates a new instance with the given StateTrackingHandler.Listener.

Method Summary

Modifier and Type	Method	Description
void	dump(Appendable out, String indent)
long	getDemandCallbackTimeout()
long	getHandlerCallbackTimeout()
long	getWriteCallbackTimeout()
long	getWriteTimeout()
boolean	handle(Request originalRequest, Response originalResponse, org.eclipse.jetty.util.Callback originalCallback)	Invoked to handle the passed HTTP request and response.
boolean	isCompleteHandlerCallbackAtTimeout()
void	setCompleteHandlerCallbackAtTimeout(boolean completeHandlerCallbackAtTimeout)
void	setDemandCallbackTimeout(long timeout)
void	setHandlerCallbackTimeout(long timeout)
void	setWriteCallbackTimeout(long timeout)
void	setWriteTimeout(long timeout)
String	toString()

Methods inherited from class org.eclipse.jetty.server.Handler.Wrapper

getHandler, getInvocationType, setHandler

Methods inherited from class org.eclipse.jetty.server.Handler.AbstractContainer

findContainerOf, getDescendant, getDescendants, isDynamic, setDynamic, setServer

Methods inherited from class org.eclipse.jetty.server.Handler.Abstract

destroy, doStart, doStop, getServer

Methods inherited from class org.eclipse.jetty.util.component.ContainerLifeCycle

addBean, addBean, addEventListener, addManaged, contains, dump, dump, dumpObjects, dumpStdErr, getBean, getBeans, getBeans, getContainedBeans, getContainedBeans, installBean, installBean, isAuto, isManaged, isUnmanaged, manage, removeBean, removeBeans, removeEventListener, setBeans, start, stop, unmanage, updateBean, updateBean, updateBeans, updateBeans

Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

getEventListeners, getState, getState, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, setEventListeners, start, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

getCachedBeans, getEventListeners

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

destroy

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

dumpSelf

Methods inherited from interface org.eclipse.jetty.util.component.Dumpable.DumpableContainer

isDumpable

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

getServer, setServer

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

getContainer, getDescendant, getDescendants, getDescendants

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

getHandlers, getTail, insertHandler, setHandler

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

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

Constructor Details

StateTrackingHandler

public StateTrackingHandler()

Creates a new instance with a default StateTrackingHandler.Listener that logs events at warning level.

StateTrackingHandler

public StateTrackingHandler(StateTrackingHandler.Listener listener)

Creates a new instance with the given StateTrackingHandler.Listener.

Parameters:

listener - the event listener

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:

• getHandlerCallbackTimeout()

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,
 org.eclipse.jetty.util.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:

• Request.Handler.AbortException

dump

public void dump(Appendable out,
 String indent)
          throws IOException

Specified by:

dump in interface org.eclipse.jetty.util.component.Dumpable

Overrides:

dump in class org.eclipse.jetty.util.component.ContainerLifeCycle

Throws:

IOException

toString

public String toString()

Overrides:

toString in class org.eclipse.jetty.util.component.AbstractLifeCycle