Requirements for a Jakarta WebSockets Whiteboard

[tcalmant]

Initial version of the requirements for the proposal of Jakarta WebSocket Whiteboard as described in #575

[stbischof]

@tcalmant could you look for your eclipse foundation eca declaration? and you need to sign-off the commits.

@timothyjward you may could assist.

[tcalmant]

@tcalmant could you look for your eclipse foundation eca declaration? and you need to sign-off the commits.

Fixed. Sorry, I used the wrong email address for ECA.

[grgrzybek]

For the record, Pax Web 8 implements whiteboard tracker for web sockets and the details are:

• the service filter (|(org.ops4j.pax.web.http.whiteboard.websocket=true)(websocket=true)) is used here
• services of objectClass=java.lang.Object are tracked (as any annotated class can be used)
• an @javax.websocket.server.ServerEndpoint annotation is taken from the class of service object to get some metadata (like path, decoders/encoders and subprotocols) here
• the important implementation aspect is that websockets for running jetty/tomcat/undertow can be correctly installed via SCIs, so special PaxWebWebSocketsServletContainerInitializer is used that does the magic
• Pax Web doesn't necessarily instantiate the websocket endpoint - actually registered object is used as is (so the websocket endpoint instance used is the same as the one registered)
• when Class object is registered, javax.websocket.server.ServerContainer#addEndpoint(java.lang.Class<?>) is called
• when actual Object is registered, javax.websocket.server.ServerContainer#addEndpoint(javax.websocket.server.ServerEndpointConfig)) is called that uses existing instance
• Pax Web ensures that the behavior is consistent for Jetty, Tomcat and Undertow
• Here's the integration test: https://github.com/ops4j/org.ops4j.pax.web/blob/web-8.0.20/pax-web-itest/pax-web-itest-container/pax-web-itest-container-common/src/main/java/org/ops4j/pax/web/itest/container/websockets/AbstractWebSocketWhiteBoardIntegrationTest.java

@tcalmant I checked your draft specification and it roughly matches to what is available in Pax Web.
I didn't think about dedicated annotations like @WebSocketWhiteboardServletPattern - I simply used the one from JSR 356 (@javax.websocket.server.ServerEndpoint)

Also while from JakartaEE point of view, Servlets and WebSockets are different specs, in Pax Web I treated servlets (+filters, listeners, error pages, ...) and websockets in exactly the same way. With this in mind I could look at this proposal as kind of "extension" of Http Whiteboard (now Servlet Whiteboard) OSGi CMPN specification. Of course it's nice to have separate chapter. I'd simply emphasize it's kind of like Servlet Whiteboard specification got extra service to track (WebSocket endpoint class or instance).

I definitely don't feel like I should dictate here. Simply if you want, please have a look at how Pax Web implements WebSocket whiteboard-tracking already.

regards
Grzegorz Grzybek

[timothyjward]

After today's call it feels like we're moving beyond requirement gathering. Most of the discussion was about the feasibility of implementing the requirements as written.

At the next call we should consider whether we're ready to move to the next stage (i.e. spec and design)

As for implementation, it appears that most implementations are container specific, i.e. they cannot be deployed in a generic web container. The Tyrus Servlet Container however appears to be platform agnostic. This could be suitable for a generic websocket whiteboard implementation on top of the servlet whiteboard, implemented using a Filter or similar.

Other container specific implementations could be created using the native adapters (e.g. Jetty or Undertow)

[grgrzybek]

For Tyrus I did a quick check

• it indeed is a standalone WebSocket server implementation
• org.glassfish.tyrus.servlet.TyrusServletFilter is a bridge from web application (web.xml, WAR) into Tyrus
• this filter uses org.glassfish.tyrus.servlet.TyrusHttpUpgradeHandler which deals with WebSockets protocol by taking the data directly from jakarta.servlet.http.WebConnection (and its in/out streams)
• this filter + upgrade handler are part of org.glassfish.tyrus:tyrus-container-servlet Maven module
• the standalone implementation is org.glassfish.tyrus:tyrus-core