Interface LifecycleObserver

public interface LifecycleObserver

Read-only hook methods for observing system and request lifecycle events.

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).

A standard threadsafe implementation can be acquired via the defaultInstance() factory method.

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

Author:

Mark Allen

Method Summary

Modifier and Type	Method	Description
static @NonNull LifecycleObserver	defaultInstance()	Acquires a threadsafe LifecycleObserver instance with sensible defaults.
default void	didAcceptConnection(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress)	Called after a server accepts a new TCP connection.
default void	didAcceptRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget)	Called after a request is accepted for application-level handling.
default void	didEstablishServerSentEventConnection(@NonNull ServerSentEventConnection serverSentEventConnection)	Called after an SSE connection is established.
default void	didFailToAcceptConnection(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @NonNull ConnectionRejectionReason reason, @Nullable Throwable throwable)	Called after a server fails to accept a new TCP connection.
default void	didFailToAcceptRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget, @NonNull RequestRejectionReason reason, @Nullable Throwable throwable)	Called when a request fails to be accepted before application-level handling begins.
default void	didFailToEstablishServerSentEventConnection(@NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull ServerSentEventConnection.HandshakeFailureReason reason, @Nullable Throwable throwable)	Called if an SSE connection fails to establish.
default void	didFailToReadRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget, @NonNull RequestReadFailureReason reason, @Nullable Throwable throwable)	Called when a request could not be read or parsed into a valid Request.
default void	didFailToStartServer(@NonNull Server server, @NonNull Throwable throwable)	Called after a Server instance was asked to start, but failed due to an exception.
default void	didFailToStartServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer, @NonNull Throwable throwable)	Called after a ServerSentEventServer instance was asked to start, but failed due to an exception.
default void	didFailToStartSoklet(@NonNull Soklet soklet, @NonNull Throwable throwable)	Called after a Soklet instance was asked to start, but failed due to an exception.
default void	didFailToStopServer(@NonNull Server server, @NonNull Throwable throwable)	Called after a Server instance was asked to stop, but failed due to an exception.
default void	didFailToStopServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer, @NonNull Throwable throwable)	Called after a ServerSentEventServer instance was asked to stop, but failed due to an exception.
default void	didFailToStopSoklet(@NonNull Soklet soklet, @NonNull Throwable throwable)	Called after a Soklet instance was asked to stop, but failed due to an exception.
default void	didFailToWriteResponse(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull MarshaledResponse marshaledResponse, @NonNull Duration responseWriteDuration, @NonNull Throwable throwable)	Called after response data fails to write.
default void	didFailToWriteServerSentEvent(@NonNull ServerSentEventConnection serverSentEventConnection, @NonNull ServerSentEvent serverSentEvent, @NonNull Duration writeDuration, @NonNull Throwable throwable)	Called after an SSE event fails to write.
default void	didFailToWriteServerSentEventComment(@NonNull ServerSentEventConnection serverSentEventConnection, @NonNull ServerSentEventComment serverSentEventComment, @NonNull Duration writeDuration, @NonNull Throwable throwable)	Called after an SSE comment fails to write.
default void	didFinishRequestHandling(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull MarshaledResponse marshaledResponse, @NonNull Duration duration, @NonNull List<@NonNull Throwable> throwables)	Called after a request finishes processing.
default void	didReadRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget)	Called when a request was successfully read or parsed into a valid Request.
default void	didReceiveLogEvent(@NonNull LogEvent logEvent)	Called when Soklet emits a log event.
default void	didStartRequestHandling(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod)	Called as soon as a request is received and a Resource Method has been resolved to handle it.
default void	didStartServer(@NonNull Server server)	Called after the server starts.
default void	didStartServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer)	Called after the SSE server starts.
default void	didStartSoklet(@NonNull Soklet soklet)	Called after a Soklet instance starts.
default void	didStopServer(@NonNull Server server)	Called after the server stops.
default void	didStopServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer)	Called after the SSE server stops.
default void	didStopSoklet(@NonNull Soklet soklet)	Called after a Soklet instance stops.
default void	didTerminateServerSentEventConnection(@NonNull ServerSentEventConnection serverSentEventConnection, @NonNull Duration connectionDuration, @NonNull ServerSentEventConnection.TerminationReason terminationReason, @Nullable Throwable throwable)	Called after an SSE connection is terminated.
default void	didWriteResponse(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull MarshaledResponse marshaledResponse, @NonNull Duration responseWriteDuration)	Called after response data is written.
default void	didWriteServerSentEvent(@NonNull ServerSentEventConnection serverSentEventConnection, @NonNull ServerSentEvent serverSentEvent, @NonNull Duration writeDuration)	Called after an SSE event is written.
default void	didWriteServerSentEventComment(@NonNull ServerSentEventConnection serverSentEventConnection, @NonNull ServerSentEventComment serverSentEventComment, @NonNull Duration writeDuration)	Called after an SSE comment is written.
default void	willAcceptConnection(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress)	Called when a server is about to accept a new TCP connection.
default void	willAcceptRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget)	Called when a request is about to be accepted for application-level handling.
default void	willEstablishServerSentEventConnection(@NonNull Request request, @Nullable ResourceMethod resourceMethod)	Called before an SSE connection is established.
default void	willReadRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget)	Called when Soklet is about to read or parse a request into a valid Request.
default void	willStartServer(@NonNull Server server)	Called before the server starts.
default void	willStartServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer)	Called before the SSE server starts.
default void	willStartSoklet(@NonNull Soklet soklet)	Called before a Soklet instance starts.
default void	willStopServer(@NonNull Server server)	Called before the server stops.
default void	willStopServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer)	Called before the SSE server stops.
default void	willStopSoklet(@NonNull Soklet soklet)	Called before a Soklet instance stops.
default void	willTerminateServerSentEventConnection(@NonNull ServerSentEventConnection serverSentEventConnection, @NonNull ServerSentEventConnection.TerminationReason terminationReason, @Nullable Throwable throwable)	Called before an SSE connection is terminated.
default void	willWriteResponse(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull MarshaledResponse marshaledResponse)	Called before response data is written.
default void	willWriteServerSentEvent(@NonNull ServerSentEventConnection serverSentEventConnection, @NonNull ServerSentEvent serverSentEvent)	Called before an SSE event is written.
default void	willWriteServerSentEventComment(@NonNull ServerSentEventConnection serverSentEventConnection, @NonNull ServerSentEventComment serverSentEventComment)	Called before an SSE comment is written.

Method Details

willStartSoklet

default void willStartSoklet(@NonNull Soklet soklet)

Called before a Soklet instance starts.

didStartSoklet

default void didStartSoklet(@NonNull Soklet soklet)

Called after a Soklet instance starts.

didFailToStartSoklet

default void didFailToStartSoklet(@NonNull Soklet soklet,
 @NonNull Throwable throwable)

Called after a Soklet instance was asked to start, but failed due to an exception.

willStopSoklet

default void willStopSoklet(@NonNull Soklet soklet)

Called before a Soklet instance stops.

didStopSoklet

default void didStopSoklet(@NonNull Soklet soklet)

Called after a Soklet instance stops.

didFailToStopSoklet

default void didFailToStopSoklet(@NonNull Soklet soklet,
 @NonNull Throwable throwable)

Called after a Soklet instance was asked to stop, but failed due to an exception.

willStartServer

default void willStartServer(@NonNull Server server)

Called before the server starts.

didStartServer

default void didStartServer(@NonNull Server server)

Called after the server starts.

didFailToStartServer

default void didFailToStartServer(@NonNull Server server,
 @NonNull Throwable throwable)

Called after a Server instance was asked to start, but failed due to an exception.

willStopServer

default void willStopServer(@NonNull Server server)

Called before the server stops.

didStopServer

default void didStopServer(@NonNull Server server)

Called after the server stops.

didFailToStopServer

default void didFailToStopServer(@NonNull Server server,
 @NonNull Throwable throwable)

Called after a Server instance was asked to stop, but failed due to an exception.

willAcceptConnection

default void willAcceptConnection(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress)

Called when a server is about to accept a new TCP connection.

Parameters:

serverType - the server type that is accepting the connection

remoteAddress - the best-effort remote address, or null if unavailable

didAcceptConnection

default void didAcceptConnection(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress)

Called after a server accepts a new TCP connection.

Parameters:

serverType - the server type that accepted the connection

remoteAddress - the best-effort remote address, or null if unavailable

didFailToAcceptConnection

default void didFailToAcceptConnection(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @NonNull ConnectionRejectionReason reason,
 @Nullable Throwable throwable)

Called after a server fails to accept a new TCP connection.

Parameters:

serverType - the server type that failed to accept the connection

remoteAddress - the best-effort remote address, or null if unavailable

reason - the failure reason

throwable - an optional underlying cause, or null if not applicable

willAcceptRequest

default void willAcceptRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget)

Called when a request is about to be accepted for application-level handling.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

didAcceptRequest

default void didAcceptRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget)

Called after a request is accepted for application-level handling.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

didFailToAcceptRequest

default void didFailToAcceptRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget,
 @NonNull RequestRejectionReason reason,
 @Nullable Throwable throwable)

Called when a request fails to be accepted before application-level handling begins.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

reason - the rejection reason

throwable - an optional underlying cause, or null if not applicable

willReadRequest

default void willReadRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget)

Called when Soklet is about to read or parse a request into a valid Request.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

didReadRequest

default void didReadRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget)

Called when a request was successfully read or parsed into a valid Request.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

didFailToReadRequest

default void didFailToReadRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget,
 @NonNull RequestReadFailureReason reason,
 @Nullable Throwable throwable)

Called when a request could not be read or parsed into a valid Request.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

reason - the failure reason

throwable - an optional underlying cause, or null if not applicable

didStartRequestHandling

default void didStartRequestHandling(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod)

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

Parameters:

serverType - the server type that received the request

didFinishRequestHandling

default void didFinishRequestHandling(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull MarshaledResponse marshaledResponse,
 @NonNull Duration duration,
 @NonNull List<@NonNull Throwable> throwables)

Called after a request finishes processing.

willWriteResponse

default void willWriteResponse(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull MarshaledResponse marshaledResponse)

Called before response data is written.

didWriteResponse

default void didWriteResponse(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull MarshaledResponse marshaledResponse,
 @NonNull Duration responseWriteDuration)

Called after response data is written.

didFailToWriteResponse

default void didFailToWriteResponse(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull MarshaledResponse marshaledResponse,
 @NonNull Duration responseWriteDuration,
 @NonNull Throwable throwable)

Called after response data fails to write.

willStartServerSentEventServer

default void willStartServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer)

Called before the SSE server starts.

didStartServerSentEventServer

default void didStartServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer)

Called after the SSE server starts.

didFailToStartServerSentEventServer

default void didFailToStartServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer,
 @NonNull Throwable throwable)

Called after a ServerSentEventServer instance was asked to start, but failed due to an exception.

willStopServerSentEventServer

default void willStopServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer)

Called before the SSE server stops.

didStopServerSentEventServer

default void didStopServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer)

Called after the SSE server stops.

didFailToStopServerSentEventServer

default void didFailToStopServerSentEventServer(@NonNull ServerSentEventServer serverSentEventServer,
 @NonNull Throwable throwable)

Called after a ServerSentEventServer instance was asked to stop, but failed due to an exception.

willEstablishServerSentEventConnection

default void willEstablishServerSentEventConnection(@NonNull Request request,
 @Nullable ResourceMethod resourceMethod)

Called before an SSE connection is established.

didEstablishServerSentEventConnection

default void didEstablishServerSentEventConnection(@NonNull ServerSentEventConnection serverSentEventConnection)

Called after an SSE connection is established.

didFailToEstablishServerSentEventConnection

default void didFailToEstablishServerSentEventConnection(@NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull ServerSentEventConnection.HandshakeFailureReason reason,
 @Nullable Throwable throwable)

Called if an SSE connection fails to establish.

Parameters:

reason - the handshake failure reason

throwable - an optional underlying cause, or null if not applicable

willTerminateServerSentEventConnection

default void willTerminateServerSentEventConnection(@NonNull ServerSentEventConnection serverSentEventConnection,
 @NonNull ServerSentEventConnection.TerminationReason terminationReason,
 @Nullable Throwable throwable)

Called before an SSE connection is terminated.

didTerminateServerSentEventConnection

default void didTerminateServerSentEventConnection(@NonNull ServerSentEventConnection serverSentEventConnection,
 @NonNull Duration connectionDuration,
 @NonNull ServerSentEventConnection.TerminationReason terminationReason,
 @Nullable Throwable throwable)

Called after an SSE connection is terminated.

willWriteServerSentEvent

default void willWriteServerSentEvent(@NonNull ServerSentEventConnection serverSentEventConnection,
 @NonNull ServerSentEvent serverSentEvent)

Called before an SSE event is written.

didWriteServerSentEvent

default void didWriteServerSentEvent(@NonNull ServerSentEventConnection serverSentEventConnection,
 @NonNull ServerSentEvent serverSentEvent,
 @NonNull Duration writeDuration)

Called after an SSE event is written.

didFailToWriteServerSentEvent

default void didFailToWriteServerSentEvent(@NonNull ServerSentEventConnection serverSentEventConnection,
 @NonNull ServerSentEvent serverSentEvent,
 @NonNull Duration writeDuration,
 @NonNull Throwable throwable)

Called after an SSE event fails to write.

willWriteServerSentEventComment

default void willWriteServerSentEventComment(@NonNull ServerSentEventConnection serverSentEventConnection,
 @NonNull ServerSentEventComment serverSentEventComment)

Called before an SSE comment is written.

didWriteServerSentEventComment

default void didWriteServerSentEventComment(@NonNull ServerSentEventConnection serverSentEventConnection,
 @NonNull ServerSentEventComment serverSentEventComment,
 @NonNull Duration writeDuration)

Called after an SSE comment is written.

didFailToWriteServerSentEventComment

default void didFailToWriteServerSentEventComment(@NonNull ServerSentEventConnection serverSentEventConnection,
 @NonNull ServerSentEventComment serverSentEventComment,
 @NonNull Duration writeDuration,
 @NonNull Throwable throwable)

Called after an SSE comment fails to write.

didReceiveLogEvent

default void didReceiveLogEvent(@NonNull LogEvent logEvent)

Called when Soklet emits a log event.

defaultInstance

static @NonNull LifecycleObserver defaultInstance()

Acquires a threadsafe LifecycleObserver instance with sensible defaults.

Returns:

a LifecycleObserver with default settings