Interface LifecycleInterceptor

All Known Implementing Classes:

DefaultLifecycleInterceptor

public interface LifecycleInterceptor

"Hook" methods for customizing behavior in response to system lifecycle events - server started, request received, response written, and so on.

The ability to modify request processing control flow is provided via wrapRequest(Request, ResourceMethod, Consumer) and interceptRequest(Request, ResourceMethod, Function, Consumer).

Note: some of these methods are "fail-fast" - exceptions thrown will bubble out and stop execution - and for others, Soklet will catch exceptions and surface separately via didReceiveLogEvent(LogEvent). Generally speaking, lifecycle events that are scoped at the server level (e.g. willStartServer(Server)) will fail-fast and events that are scoped at the request level (e.g. didStartRequestHandling(Request, ResourceMethod)) will not fail-fast.

Full documentation is available at https://www.soklet.com/docs/request-lifecycle.

Author:

Mark Allen

Method Summary

Modifier and Type	Method	Description
default void	didEstablishServerSentEventConnection(Request request, ResourceMethod resourceMethod)	Called immediately after a Server-Sent Event connection of indefinite duration to the client is opened.
default void	didFinishRequestHandling(Request request, ResourceMethod resourceMethod, MarshaledResponse marshaledResponse, Duration processingDuration, List<Throwable> throwables)	Called after a request has fully completed processing and a response has been sent to the client.
default void	didFinishResponseWriting(Request request, ResourceMethod resourceMethod, MarshaledResponse marshaledResponse, Duration responseWriteDuration, Throwable throwable)	Called after the response is sent to the client.
default void	didFinishServerSentEventWriting(Request request, ResourceMethod resourceMethod, ServerSentEvent serverSentEvent, Duration writeDuration, Throwable throwable)	Called after a Server-Sent Event is sent to the client.
default void	didReceiveLogEvent(LogEvent logEvent)	Called when an event suitable for logging occurs during processing (generally, an exception).
default void	didStartRequestHandling(Request request, ResourceMethod resourceMethod)	Called as soon as a request is received and a Resource Method has been resolved to handle it.
default void	didStartServer(Server server)	Called after the server starts.
default void	didStartServerSentEventServer(ServerSentEventServer serverSentEventServer)	Called after the Server-Sent Event server starts.
default void	didStopServer(Server server)	Called after the server stops.
default void	didStopServerSentEventServer(ServerSentEventServer serverSentEventServer)	Called after the Server-Sent Event server stops.
default void	didTerminateServerSentEventConnection(Request request, ResourceMethod resourceMethod, Duration connectionDuration, Throwable throwable)	Called immediately after a Server-Sent Event connection to the client is terminated.
default void	interceptRequest(Request request, ResourceMethod resourceMethod, Function<Request,MarshaledResponse> responseProducer, Consumer<MarshaledResponse> responseWriter)	Supports alteration of the request processing flow by enabling programmatic control over its two key phases: acquiring a response and writing the response to the client.
default void	willEstablishServerSentEventConnection(Request request, ResourceMethod resourceMethod)	Called immediately before a Server-Sent Event connection of indefinite duration to the client is opened.
default void	willStartResponseWriting(Request request, ResourceMethod resourceMethod, MarshaledResponse marshaledResponse)	Called before the response is sent to the client.
default void	willStartServer(Server server)	Called before the server starts.
default void	willStartServerSentEventServer(ServerSentEventServer serverSentEventServer)	Called before the Server-Sent Event server starts.
default void	willStartServerSentEventWriting(Request request, ResourceMethod resourceMethod, ServerSentEvent serverSentEvent)	Called before a Server-Sent Event is sent to the client.
default void	willStopServer(Server server)	Called before the server stops.
default void	willStopServerSentEventServer(ServerSentEventServer serverSentEventServer)	Called before the Server-Sent Event server stops.
default void	willTerminateServerSentEventConnection(Request request, ResourceMethod resourceMethod, Throwable throwable)	Called immediately before a Server-Sent Event connection to the client is terminated.
default void	wrapRequest(Request request, ResourceMethod resourceMethod, Consumer<Request> requestProcessor)	Wraps around the whole "outside" of the entire request-handling flow.

Method Details

willStartServer

default void willStartServer(@Nonnull
 Server server)

Called before the server starts.

This method is fail-fast. If an exception occurs when Soklet invokes this method, it will halt execution and bubble out for your application code to handle.

Parameters:

server - the server that will start

didStartServer

default void didStartServer(@Nonnull
 Server server)

Called after the server starts.

This method is fail-fast. If an exception occurs when Soklet invokes this method, it will halt execution and bubble out for your application code to handle.

Parameters:

server - the server that started

willStopServer

default void willStopServer(@Nonnull
 Server server)

Called before the server stops.

This method is fail-fast. If an exception occurs when Soklet invokes this method, it will halt execution and bubble out for your application code to handle.

Parameters:

server - the server that will stop

didStopServer

default void didStopServer(@Nonnull
 Server server)

Called after the server stops.

This method is fail-fast. If an exception occurs when Soklet invokes this method, it will halt execution and bubble out for your application code to handle.

Parameters:

server - the server that stopped

didStartRequestHandling

default void didStartRequestHandling(@Nonnull
 Request request,
 @Nullable
 ResourceMethod resourceMethod)

Called as soon as a request is received and a Resource Method has been resolved to handle it.

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_DID_START_REQUEST_HANDLING_FAILED.

Parameters:

request - the request that was received

resourceMethod - the Resource Method that will handle the request May be null if no Resource Method was resolved, e.g. a 404

didFinishRequestHandling

default void didFinishRequestHandling(@Nonnull
 Request request,
 @Nullable
 ResourceMethod resourceMethod,
 @Nonnull
 MarshaledResponse marshaledResponse,
 @Nonnull
 Duration processingDuration,
 @Nonnull
 List<Throwable> throwables)

Called after a request has fully completed processing and a response has been sent to the client.

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_DID_FINISH_REQUEST_HANDLING_FAILED.

Parameters:

request - the request that was received

resourceMethod - the Resource Method that will handle the request May be null if no Resource Method was resolved, e.g. a 404

marshaledResponse - the response that was sent to the client

processingDuration - how long it took to process the whole request, including time to send the response to the client

throwables - exceptions that occurred during request handling

willStartResponseWriting

default void willStartResponseWriting(@Nonnull
 Request request,
 @Nullable
 ResourceMethod resourceMethod,
 @Nonnull
 MarshaledResponse marshaledResponse)

Called before the response is sent to the client.

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_WILL_START_RESPONSE_WRITING_FAILED.

Parameters:

request - the request that was received

resourceMethod - the Resource Method that handled the request. May be null if no Resource Method was resolved, e.g. a 404

marshaledResponse - the response to send to the client

didFinishResponseWriting

default void didFinishResponseWriting(@Nonnull
 Request request,
 @Nullable
 ResourceMethod resourceMethod,
 @Nonnull
 MarshaledResponse marshaledResponse,
 @Nonnull
 Duration responseWriteDuration,
 @Nullable
 Throwable throwable)

Called after the response is sent to the client.

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_DID_FINISH_RESPONSE_WRITING_FAILED.

Parameters:

request - the request that was received

resourceMethod - the Resource Method that handled the request. May be null if no Resource Method was resolved, e.g. a 404

marshaledResponse - the response that was sent to the client

responseWriteDuration - how long it took to send the response to the client

throwable - the exception thrown during response writing (if any)

didReceiveLogEvent

default void didReceiveLogEvent(@Nonnull
 LogEvent logEvent)

Called when an event suitable for logging occurs during processing (generally, an exception).

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch the exception and print its stack trace to stderr.

Parameters:

logEvent - the event that occurred

interceptRequest

default void interceptRequest(@Nonnull
 Request request,
 @Nullable
 ResourceMethod resourceMethod,
 @Nonnull
 Function<Request,MarshaledResponse> responseProducer,
 @Nonnull
 Consumer<MarshaledResponse> responseWriter)

Supports alteration of the request processing flow by enabling programmatic control over its two key phases: acquiring a response and writing the response to the client.

This is a more fine-grained approach than wrapRequest(Request, ResourceMethod, Consumer).

 // Default implementation: first, acquire a response for the given request.
 MarshaledResponse marshaledResponse = responseProducer.apply(request);

 // Second, send the response over the wire.
 responseWriter.accept(marshaledResponse);

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_INTERCEPT_REQUEST_FAILED.

See https://www.soklet.com/docs/request-lifecycle#request-intercepting for detailed documentation.

Parameters:

request - the request that was received

resourceMethod - the Resource Method that will handle the request May be null if no Resource Method was resolved, e.g. a 404

responseProducer - function that accepts the request as input and provides a response as output (usually by invoking the Resource Method)

responseWriter - function that accepts a response as input and writes the response to the client

wrapRequest

default void wrapRequest(@Nonnull
 Request request,
 @Nullable
 ResourceMethod resourceMethod,
 @Nonnull
 Consumer<Request> requestProcessor)

Wraps around the whole "outside" of the entire request-handling flow.

The "inside" of the flow is everything from Resource Method execution to writing response bytes to the client.

This is a more coarse-grained approach than interceptRequest(Request, ResourceMethod, Function, Consumer).

 // Default implementation: let the request processing proceed as normal
 requestProcessor.accept(request);

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_WRAP_REQUEST_FAILED.

See https://www.soklet.com/docs/request-lifecycle#request-wrapping for detailed documentation.

Parameters:

request - the request that was received

resourceMethod - the Resource Method that will handle the request May be null if no Resource Method was resolved, e.g. a 404

requestProcessor - function that takes the request as input and performs all downstream processing

willStartServerSentEventServer

default void willStartServerSentEventServer(@Nonnull
 ServerSentEventServer serverSentEventServer)

Called before the Server-Sent Event server starts.

This method is fail-fast. If an exception occurs when Soklet invokes this method, it will halt execution and bubble out for your application code to handle.

Parameters:

serverSentEventServer - the Server-Sent Event server that will start

didStartServerSentEventServer

default void didStartServerSentEventServer(@Nonnull
 ServerSentEventServer serverSentEventServer)

Called after the Server-Sent Event server starts.

This method is fail-fast. If an exception occurs when Soklet invokes this method, it will halt execution and bubble out for your application code to handle.

Parameters:

serverSentEventServer - the Server-Sent Event server that started

willStopServerSentEventServer

default void willStopServerSentEventServer(@Nonnull
 ServerSentEventServer serverSentEventServer)

Called before the Server-Sent Event server stops.

This method is fail-fast. If an exception occurs when Soklet invokes this method, it will halt execution and bubble out for your application code to handle.

Parameters:

serverSentEventServer - the Server-Sent Event server that will stop

didStopServerSentEventServer

default void didStopServerSentEventServer(@Nonnull
 ServerSentEventServer serverSentEventServer)

Called after the Server-Sent Event server stops.

This method is fail-fast. If an exception occurs when Soklet invokes this method, it will halt execution and bubble out for your application code to handle.

Parameters:

serverSentEventServer - the Server-Sent Event server that stopped

willEstablishServerSentEventConnection

default void willEstablishServerSentEventConnection(@Nonnull
 Request request,
 @Nonnull
 ResourceMethod resourceMethod)

Called immediately before a Server-Sent Event connection of indefinite duration to the client is opened.

This occurs after the initial "handshake" Server-Sent Event request has successfully completed (that is, an HTTP 200 response).

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_WILL_ESTABLISH_SERVER_SENT_EVENT_CONNECTION_FAILED.

Parameters:

request - the initial "handshake" Server-Sent Event request that was received

resourceMethod - the Resource Method that handled the "handshake"

didEstablishServerSentEventConnection

default void didEstablishServerSentEventConnection(@Nonnull
 Request request,
 @Nonnull
 ResourceMethod resourceMethod)

Called immediately after a Server-Sent Event connection of indefinite duration to the client is opened.

This occurs after the initial "handshake" Server-Sent Event request has successfully completed (that is, an HTTP 200 response).

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_DID_ESTABLISH_SERVER_SENT_EVENT_CONNECTION_FAILED.

Parameters:

request - the initial "handshake" Server-Sent Event request that was received

resourceMethod - the Resource Method that handled the "handshake"

willTerminateServerSentEventConnection

default void willTerminateServerSentEventConnection(@Nonnull
 Request request,
 @Nonnull
 ResourceMethod resourceMethod,
 @Nullable
 Throwable throwable)

Called immediately before a Server-Sent Event connection to the client is terminated.

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_WILL_TERMINATE_SERVER_SENT_EVENT_CONNECTION_FAILED.

Parameters:

request - the initial "handshake" Server-Sent Event request that was received

resourceMethod - the Resource Method that handled the "handshake"

throwable - the exception thrown which caused the connection to terminate (if any)

didTerminateServerSentEventConnection

default void didTerminateServerSentEventConnection(@Nonnull
 Request request,
 @Nonnull
 ResourceMethod resourceMethod,
 @Nonnull
 Duration connectionDuration,
 @Nullable
 Throwable throwable)

Called immediately after a Server-Sent Event connection to the client is terminated.

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_DID_TERMINATE_SERVER_SENT_EVENT_CONNECTION_FAILED.

Parameters:

request - the initial "handshake" Server-Sent Event request that was received

resourceMethod - the Resource Method that handled the "handshake"

connectionDuration - how long the connection was open for

throwable - the exception thrown which caused the connection to terminate (if any)

willStartServerSentEventWriting

default void willStartServerSentEventWriting(@Nonnull
 Request request,
 @Nonnull
 ResourceMethod resourceMethod,
 @Nonnull
 ServerSentEvent serverSentEvent)

Called before a Server-Sent Event is sent to the client.

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_WILL_START_SERVER_SENT_EVENT_WRITING_FAILED.

Parameters:

request - the initial "handshake" Server-Sent Event request that was received

resourceMethod - the Resource Method that handled the "handshake"

serverSentEvent - the Server-Sent Event to send to the client

didFinishServerSentEventWriting

default void didFinishServerSentEventWriting(@Nonnull
 Request request,
 @Nonnull
 ResourceMethod resourceMethod,
 @Nonnull
 ServerSentEvent serverSentEvent,
 @Nonnull
 Duration writeDuration,
 @Nullable
 Throwable throwable)

Called after a Server-Sent Event is sent to the client.

This method is not fail-fast. If an exception occurs when Soklet invokes this method, Soklet will catch it and invoke didReceiveLogEvent(LogEvent) with type LogEventType.LIFECYCLE_INTERCEPTOR_DID_FINISH_SERVER_SENT_EVENT_WRITING_FAILED.

Parameters:

request - the initial "handshake" Server-Sent Event request that was received

resourceMethod - the Resource Method that handled the "handshake"

serverSentEvent - the Server-Sent Event that was sent to the client

writeDuration - how long it took to send the Server-Sent Event to the client

throwable - the exception thrown during Server-Sent Event writing (if any)