Package pl.morgwai.base.servlet.guice.scopes

Class GuiceServerEndpointConfigurator

java.lang.Object

jakarta.websocket.server.ServerEndpointConfig.Configurator

pl.morgwai.base.servlet.guice.scopes.GuiceServerEndpointConfigurator

Direct Known Subclasses:

PingingEndpointConfigurator

public class GuiceServerEndpointConfigurator
extends ServerEndpointConfig.Configurator

Obtains Endpoint instances from Guice and ensures their methods run within websocket Contexts. This way, all dependencies are injected and Scopes from ServletModule (ServletModule.containerCallScope, ServletModule.websocketConnectionScope and ServletModule.httpSessionScope) work properly.

To use this Configurator for programmatically added Endpoints, create an instance using GuiceServerEndpointConfigurator(ServletContext) and pass it to the config:

 final var configurator = new GuiceServerEndpointConfigurator(servletContext);
 websocketContainer.addEndpoint(
     ServerEndpointConfig.Builder
         .create(MyProgrammaticEndpoint.class, "/websocket/programmatic")
         .configurator(configurator)
         .build()
 );

To use this Configurator for @ServerEndpoint annotated Endpoints, first the app-wide Injector must be stored as a deployment attribute under the fully-qualified name of Injector class in contextInitialized(event) method of app's ServletContextListener.
Secondly, registerDeployment(ServletContext) and deregisterDeployment(ServletContext) static methods must be called respectively in contextInitialized(event) and contextDestroyed(event) methods of app's ServletContextListener.
This way container-created instances (with the param-less constructor) of this Configurator can obtain a reference to the Injector. Note that if app's Listener extends GuiceServletContextListener, the whole above setup is automatically taken care of.
Finally, Endpoint methods annotated with @OnOpen must have a Session param.
After the above conditions are met, simply pass this class as configurator param of the annotation:

 @ServerEndpoint(
         value = "/websocket/annotated",
         configurator = GuiceServerEndpointConfigurator.class)
 public class MyAnnotatedEndpoint {

     @OnOpen public void onOpen(
         Session connection  // other optional params here...
     ) {
         // ...
     }

     // other methods here...
 }

NOTE: due to the way most debuggers work, it is strongly recommended for toString() methods of Endpoints to work properly even when called outside of any Context.

See Also:

GuiceServletContextListener

Field Summary

Fields

Modifier and Type	Field	Description
protected ServletContext	appDeployment
protected ContextTracker<ContainerCallContext>	ctxTracker
protected Injector	injector

Constructor Summary

Constructors

Constructor	Description
GuiceServerEndpointConfigurator()	Necessary for ServerEndpoint annotated Endpoints.
GuiceServerEndpointConfigurator(ServletContext appDeployment)	For GuiceServletContextListener managed instance.

Method Summary

Modifier and Type	Method	Description
static void	deregisterDeployment(ServletContext appDeployment)	Removes a reference to appDeployment.
protected InvocationHandler	getAdditionalDecorator(Object endpoint)	Subclasses may override this method to further customize Endpoints.
<EndpointT> EndpointT	getEndpointInstance(Class<EndpointT> endpointClass)	Obtains an instance of endpointClass from Guice and creates a context-aware proxy for it, so that Endpoint lifecycle methods are executed within ContainerCallContext and WebsocketConnectionContext.
protected HashSet<Class<? extends Annotation>>	getRequiredEndpointMethodAnnotationTypes()	Returns a set of annotations of Endpoint lifecycle methods that are required to be present in Endpoint classes using this configurator.
protected void	initialize(ServletContext appDeployment)	Initializes this instance member fields with references from appDeployment attributes.
void	modifyHandshake(ServerEndpointConfig config, HandshakeRequest request, HandshakeResponse response)	Stores into user properties the HttpSession associated with request.
static void	registerDeployment(ServletContext appDeployment)	Registers appDeployment to be used by container-created GuiceServerEndpointConfigurator instances.

Methods inherited from class jakarta.websocket.server.ServerEndpointConfig.Configurator

checkOrigin, getNegotiatedExtensions, getNegotiatedSubprotocol

Methods inherited from class java.lang.Object

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

Field Detail

appDeployment

protected volatile ServletContext appDeployment

injector

protected Injector injector

ctxTracker

protected ContextTracker<ContainerCallContext> ctxTracker

Constructor Detail

GuiceServerEndpointConfigurator

public GuiceServerEndpointConfigurator()

Necessary for ServerEndpoint annotated Endpoints.

GuiceServerEndpointConfigurator

public GuiceServerEndpointConfigurator(ServletContext appDeployment)

For GuiceServletContextListener managed instance.

Method Detail

registerDeployment

public static void registerDeployment(ServletContext appDeployment)

Registers appDeployment to be used by container-created GuiceServerEndpointConfigurator instances.

This method is called automatically by GuiceServletContextListener.contextInitialized(jakarta.servlet.ServletContextEvent), it must be called manually in apps that don't use it.

deregisterDeployment

public static void deregisterDeployment(ServletContext appDeployment)

Removes a reference to appDeployment.

This method is called automatically by GuiceServletContextListener.contextDestroyed(jakarta.servlet.ServletContextEvent), it must be called manually in apps that don't use it.

initialize

protected void initialize(ServletContext appDeployment)

Initializes this instance member fields with references from appDeployment attributes. Called either by GuiceServerEndpointConfigurator(ServletContext) or by modifyHandshake(ServerEndpointConfig, HandshakeRequest, HandshakeResponse) in case of container-created instances for Endpoints annotated with ServerEndpoint.

getEndpointInstance

public <EndpointT> EndpointT getEndpointInstance(Class<EndpointT> endpointClass)
                                          throws InstantiationException

Obtains an instance of endpointClass from Guice and creates a context-aware proxy for it, so that Endpoint lifecycle methods are executed within ContainerCallContext and WebsocketConnectionContext.

Overrides:

getEndpointInstance in class ServerEndpointConfig.Configurator

Returns:

a proxy for the newly created endpointClass instance.

Throws:

InstantiationException

getRequiredEndpointMethodAnnotationTypes

protected HashSet<Class<? extends Annotation>> getRequiredEndpointMethodAnnotationTypes()

Returns a set of annotations of Endpoint lifecycle methods that are required to be present in Endpoint classes using this configurator. By default a singleton of OnOpen. Subclasses may override this method if needed by calling super and adding their required annotations to the obtained set before returning it.

modifyHandshake

public void modifyHandshake(ServerEndpointConfig config,
                            HandshakeRequest request,
                            HandshakeResponse response)

Stores into user properties the HttpSession associated with request.

For Configurator instances created by the container (as a result of providing this class as a ServerEndpoint.configurator() argument of some annotated Endpoint class), this method will also call initialize(ServletContext) on its first invocation.

Overrides:

modifyHandshake in class ServerEndpointConfig.Configurator

getAdditionalDecorator

protected InvocationHandler getAdditionalDecorator(Object endpoint)

Subclasses may override this method to further customize Endpoints. InvocationHandler.invoke(Object, Method, Object[]) method of the returned handler will be executed within ContainerCallContext and WebsocketConnectionContext. By default it returns a handler that simply invokes the given method on endpoint.