Module org.eclipse.jetty.server

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, 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

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.

Nested Class Summary

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, org.eclipse.jetty.util.component.Container.Listener

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.util.component.LifeCycle

org.eclipse.jetty.util.component.LifeCycle.Listener

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
EventsHandler()
EventsHandler(Handler handler)

Method Summary

Modifier and Type	Method	Description
boolean	handle(Request request, Response response, org.eclipse.jetty.util.Callback callback)	Invoked to handle the passed HTTP request and response.
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).
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).
protected void	onComplete(Request request, int status, org.eclipse.jetty.http.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).
protected void	onComplete(Request request, Throwable failure)	Deprecated. Override onComplete(Request, int, HttpFields, Throwable) instead.
protected void	onRequestRead(Request request, org.eclipse.jetty.io.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()).
protected void	onResponseBegin(Request request, int status, org.eclipse.jetty.http.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)).
protected void	onResponseTrailersComplete(Request request, org.eclipse.jetty.http.HttpFields trailers)	Invoked after the response trailers have been written and the final onResponseWriteComplete(Request, Throwable) event was fired.
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)).
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)).

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, 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, toString

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

EventsHandler

public EventsHandler()

EventsHandler

public EventsHandler(Handler handler)

Method Details

handle

public boolean handle(Request request,
 Response response,
 org.eclipse.jetty.util.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.

See Also:

• Request.Handler.AbortException

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:

• HttpChannel.onRequest(MetaData.Request)

onRequestRead

protected void onRequestRead(Request request,
 org.eclipse.jetty.io.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:

• Request.read()

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:

• HttpChannel.onRequest(MetaData.Request)

onResponseBegin

protected void onResponseBegin(Request request,
 int status,
 org.eclipse.jetty.http.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:

• Response.write(boolean, ByteBuffer, Callback)

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:

• Response.write(boolean, ByteBuffer, Callback)

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:

• Response.write(boolean, ByteBuffer, Callback)

onResponseTrailersComplete

protected void onResponseTrailersComplete(Request request,
 org.eclipse.jetty.http.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,
 org.eclipse.jetty.http.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.