Top Description Inners Fields Constructors Methods
org.eclipse.jetty.server.handler

public abstract Class EventsHandler

extends Wrapper
Class Inheritance
Known Direct Subclasses
org.eclipse.jetty.server.handler.LatencyRecordingHandler, org.eclipse.jetty.server.handler.StatisticsHandler
Imports
java.nio.ByteBuffer, java.util.function.Supplier, org.eclipse.jetty.http.HttpFields, .MetaData, org.eclipse.jetty.io.Content, org.eclipse.jetty.server.Handler, .Request, .Response, org.eclipse.jetty.util.BufferUtil, .Callback, org.slf4j.Logger, .LoggerFactory

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 and Inner Type Summary

Modifier and TypeClass and Description
private class
EventsHandler.EventsRequest

private class
EventsHandler.EventsResponse

Field Summary

Modifier and TypeField and Description
private static final Logger
LOG

Hides org.eclipse.jetty.server.Handler.Abstract.LOG.

Constructor Summary

AccessConstructor and Description
public
EventsHandler()

public
EventsHandler(Handler handler)

Method Summary

Modifier and TypeMethod and Description
public boolean
handle(Request
the HTTP request to handle
request, Response
the HTTP response to handle
response, Callback
the callback to complete when the handling is complete
callback)

Overrides org.eclipse.jetty.server.Handler.Wrapper.handle.

Implements org.eclipse.jetty.server.Request.Handler.handle.

Invoked to handle the passed HTTP request and response.

private void
notifyOnAfterHandling(Request request, boolean handled, Throwable failure)

private void
notifyOnBeforeHandling(Request request)

private void
notifyOnComplete(Request request, Throwable failure)

private void
notifyOnRequestRead(Request wrapped, Content.Chunk chunk)

private void
notifyOnResponseBegin(Request request, EventsHandler.EventsResponse response)

private void
notifyOnResponseTrailersComplete(Request request, EventsHandler.EventsResponse response)

private void
notifyOnResponseWrite(Request request, boolean last, ByteBuffer content)

private void
notifyOnResponseWriteComplete(Request request, Throwable failure)

protected void
onAfterHandling(Request
the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
request, boolean
if the server handlers handled the request
handled, Throwable
the exception thrown by the application
failure)

Invoked after application handling (i.e. just after the call to the Runnable returned from org.eclipse.jetty.server.HttpChannel#onRequest(MetaData.Request) returns).

protected void
onBeforeHandling(Request
the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
request)

Invoked just before calling the server handler tree (i.e. just before the Runnable returned from org.eclipse.jetty.server.HttpChannel#onRequest(MetaData.Request) is run).

protected void
onComplete(Request
the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
request, Throwable
if there was a failure to complete
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 org.eclipse.jetty.server.HttpChannel#onRequest(MetaData.Request) has returned and the Callback passed to Handler#handle(Request, Response, Callback) has been completed).

protected void
onRequestRead(Request
the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
request, Content.Chunk
a potentially null request content chunk, including error and org.eclipse.jetty.http.Trailers chunks. If a reference to the chunk (or its ByteBuffer) is kept, then Content.Chunk#retain() must be called.
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
the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
request, int
the response status
status, HttpFields
the immutable fields of the response object
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
the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
request, HttpFields
the written trailers.
trailers)

Invoked after the response trailers have been written and the final onResponseWriteComplete(Request, Throwable) event was fired.

protected void
onResponseWrite(Request
the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
request, boolean
indicating last write
last, ByteBuffer
The ByteBuffer of the response content chunk (readonly).
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
the request object. The read(), demand(Runnable) and fail(Throwable) methods must not be called by the listener.
request, Throwable
if there was a failure to write the given content
failure)

Invoked after each response content chunk has been written (i.e. immediately before calling the Callback passed to Response#write(boolean, ByteBuffer, Callback)).

Inherited from org.eclipse.jetty.server.Handler.Wrapper:
getHandlergetInvocationTypesetHandler

Field Detail

LOGback to summary
private static final Logger LOG

Hides org.eclipse.jetty.server.Handler.Abstract.LOG.

Constructor Detail

EventsHandlerback to summary
public EventsHandler()
EventsHandlerback to summary
public EventsHandler(Handler handler)

Method Detail

handleback to summary
public boolean handle(Request request, Response response, Callback callback) throws Exception

Overrides org.eclipse.jetty.server.Handler.Wrapper.handle.

Implements org.eclipse.jetty.server.Request.Handler.handle.

Doc from org.eclipse.jetty.server.Request.Handler.handle.

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;
}
Parameters
request:Request

the HTTP request to handle

response:Response

the HTTP response to handle

callback:Callback

the callback to complete when the handling is complete

Returns:boolean

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.

Annotations
@Override
Exceptions
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.
notifyOnAfterHandlingback to summary
private void notifyOnAfterHandling(Request request, boolean handled, Throwable failure)
notifyOnBeforeHandlingback to summary
private void notifyOnBeforeHandling(Request request)
notifyOnCompleteback to summary
private void notifyOnComplete(Request request, Throwable failure)
notifyOnRequestReadback to summary
private void notifyOnRequestRead(Request wrapped, Content.Chunk chunk)
notifyOnResponseBeginback to summary
private void notifyOnResponseBegin(Request request, EventsHandler.EventsResponse response)
notifyOnResponseTrailersCompleteback to summary
private void notifyOnResponseTrailersComplete(Request request, EventsHandler.EventsResponse response)
notifyOnResponseWriteback to summary
private void notifyOnResponseWrite(Request request, boolean last, ByteBuffer content)
notifyOnResponseWriteCompleteback to summary
private void notifyOnResponseWriteComplete(Request request, Throwable failure)
onAfterHandlingback to summary
protected void onAfterHandling(Request request, boolean handled, Throwable failure)

Invoked after application handling (i.e. just after the call to the Runnable returned from org.eclipse.jetty.server.HttpChannel#onRequest(MetaData.Request) returns).

Parameters
request:Request

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

handled:boolean

if the server handlers handled the request

failure:Throwable

the exception thrown by the application

See Also
org.eclipse.jetty.server.HttpChannel#onRequest(MetaData.Request)
onBeforeHandlingback to summary
protected void onBeforeHandling(Request request)

Invoked just before calling the server handler tree (i.e. just before the Runnable returned from org.eclipse.jetty.server.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:Request

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

See Also
org.eclipse.jetty.server.HttpChannel#onRequest(MetaData.Request)
onCompleteback to summary
protected void onComplete(Request request, 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 org.eclipse.jetty.server.HttpChannel#onRequest(MetaData.Request) has returned and the Callback passed to Handler#handle(Request, Response, Callback) has been completed).

Parameters
request:Request

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

failure:Throwable

if there was a failure to complete

onRequestReadback to summary
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:Request

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

chunk:Content.Chunk

a potentially null request content chunk, including error and org.eclipse.jetty.http.Trailers chunks. If a reference to the chunk (or its ByteBuffer) is kept, then Content.Chunk#retain() must be called.

See Also
Request#read()
onResponseBeginback to summary
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:Request

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

status:int

the response status

headers:HttpFields

the immutable fields of the response object

See Also
Response#write(boolean, ByteBuffer, Callback)
onResponseTrailersCompleteback to summary
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:Request

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

trailers:HttpFields

the written trailers.

onResponseWriteback to summary
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:Request

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

last:boolean

indicating last write

content:ByteBuffer

The ByteBuffer of the response content chunk (readonly).

See Also
Response#write(boolean, ByteBuffer, Callback)
onResponseWriteCompleteback to summary
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:Request

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

failure:Throwable

if there was a failure to write the given content

See Also
Response#write(boolean, ByteBuffer, Callback)
org.eclipse.jetty.server.handler back to summary

private Class EventsHandler.EventsRequest

extends Wrapper
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final Request
roRequest

Constructor Summary

AccessConstructor and Description
public
EventsRequest(Request request, Request roRequest)

Method Summary

Modifier and TypeMethod and Description
public Content.Chunk
read()

Overrides org.eclipse.jetty.server.Request.Wrapper.read.

Implements org.eclipse.jetty.server.Request.read.

Reads a chunk of content.

Inherited from org.eclipse.jetty.server.Request.Wrapper:
addFailureListeneraddHttpStreamWrapperaddIdleTimeoutListenerasAttributeMapclearAttributesconsumeAvailabledemandfailgetAttributegetAttributeNameSetgetBeginNanoTimegetComponentsgetConnectionMetaDatagetContextgetHeadersgetHeadersNanoTimegetHttpURIgetIdgetLengthgetMethodgetSessiongetTrailersgetTunnelSupportgetWrappedisSecurepushremoveAttributesetAttribute

Field Detail

roRequestback to summary
private final Request roRequest

Constructor Detail

EventsRequestback to summary
public EventsRequest(Request request, Request roRequest)

Method Detail

readback to summary
public Content.Chunk read()

Overrides org.eclipse.jetty.server.Request.Wrapper.read.

Implements org.eclipse.jetty.server.Request.read.

Doc from org.eclipse.jetty.server.Request.read.

Reads a chunk of content.

See how to use this method idiomatically.

The returned chunk could be:

  • null, to signal that there isn't a chunk of content available
  • an Chunk instance with non null Chunk#getFailure(), to signal that there was a failure trying to produce a chunk of content, or that the content production has been failed externally
  • a Chunk instance, containing the chunk of content.

Once a read returns an Chunk instance with non-null Chunk#getFailure() then if the failure is last further reads will continue to return the same failure chunk instance, otherwise further read() operations may return different non-failure chunks.

Once a read returns a last chunk, further reads will continue to return a last chunk (although the instance may be different).

The content reader code must ultimately arrange for a call to Chunk#release() on the returned Chunk.

Additionally, prior to the ultimate call to Chunk#release(), the reader code may make additional calls to Chunk#retain(), that must ultimately be matched by a correspondent number of calls to Chunk#release().

Concurrent reads from different threads are not recommended, as they are inherently in a race condition.

Reads performed outside the invocation context of a demand callback are allowed. However, reads performed with a pending demand are inherently in a race condition (the thread that reads with the thread that invokes the demand callback).

In addition, the returned Content.Chunk may be a Trailers instance, in case of request content trailers.

Returns:Content.Chunk

Doc from org.eclipse.jetty.io.Content.Source.read.

a chunk of content, possibly a failure instance, or null

Annotations
@Override
org.eclipse.jetty.server.handler back to summary

private Class EventsHandler.EventsResponse

extends Wrapper
Class Inheritance

Field Summary

Modifier and TypeField and Description
private boolean
notifiedOnResponseBegin

private HttpFields
suppliedTrailers

Constructor Summary

AccessConstructor and Description
public
EventsResponse(Request roRequest, Response response)

Method Summary

Modifier and TypeMethod and Description
public void
setTrailersSupplier(Supplier<HttpFields>
a supplier for the HTTP trailers
trailers)

Overrides org.eclipse.jetty.server.Response.Wrapper.setTrailersSupplier.

Implements org.eclipse.jetty.server.Response.setTrailersSupplier.

Sets the supplier for the HTTP trailers.

public void
write(boolean
whether the ByteBuffer is the last to write
last, ByteBuffer
the ByteBuffer to write
byteBuffer, Callback
the callback to notify when the write operation is complete
callback)

Overrides org.eclipse.jetty.server.Response.Wrapper.write.

Implements org.eclipse.jetty.server.Response.write.

Writes the given ByteBuffer, notifying the Callback when the write is complete.

Inherited from org.eclipse.jetty.server.Response.Wrapper:
getHeadersgetRequestgetStatusgetTrailersSuppliergetWrappedhasLastWriteisCommittedisCompletedSuccessfullyresetsetStatuswriteInterim

Field Detail

notifiedOnResponseBeginback to summary
private boolean notifiedOnResponseBegin
suppliedTrailersback to summary
private HttpFields suppliedTrailers

Constructor Detail

EventsResponseback to summary
public EventsResponse(Request roRequest, Response response)

Method Detail

setTrailersSupplierback to summary
public void setTrailersSupplier(Supplier<HttpFields> trailers)

Overrides org.eclipse.jetty.server.Response.Wrapper.setTrailersSupplier.

Implements org.eclipse.jetty.server.Response.setTrailersSupplier.

Doc from org.eclipse.jetty.server.Response.setTrailersSupplier.

Sets the supplier for the HTTP trailers.

The method Supplier#get() may be called by the implementation multiple times, so it is important that the same value is returned in every invocation.

Example:

// Correct usage.
HttpFields.Mutable trailers = HttpFields.build();
response.setTrailersSupplier(() -> trailers);

// WRONG usage, as the value changes for
// every invocation of supplier.get().
response.setTrailersSupplier(() -> HttpFields.build());
Parameters
trailers:Supplier<HttpFields>

a supplier for the HTTP trailers

Annotations
@Override
writeback to summary
public void write(boolean last, ByteBuffer byteBuffer, Callback callback)

Overrides org.eclipse.jetty.server.Response.Wrapper.write.

Implements org.eclipse.jetty.server.Response.write.

Doc from org.eclipse.jetty.server.Response.write.

Writes the given ByteBuffer, notifying the Callback when the write is complete.

Implementations guarantee that calls to this method are safely reentrant so that stack overflows are avoided in the case of mutual recursion between the execution of the Callback and a call to this method.

The invocation of the passed Callback is serialized with previous calls of this method, so that it is not invoked until any invocation of the callback of a previous call to this method has returned.

Thus a Callback should not block waiting for a callback of a future call to this method.

Parameters
last:boolean

whether the ByteBuffer is the last to write

byteBuffer:ByteBuffer

the ByteBuffer to write

callback:Callback

the callback to notify when the write operation is complete

Annotations
@Override