Provide better documentation of JettyWebSocketServletContainerInitializer and jetty-${ee-version}-websocket-jetty-server modules

[Spikhalskiy]

Problem

Spring 6.1 in JettyRequestUpgradeStrategy uses

import org.eclipse.jetty.ee10.websocket.server.JettyWebSocketCreator;
import org.eclipse.jetty.ee10.websocket.server.JettyWebSocketServerContainer;

and Spring 6.2 uses it's ee11 counterparts.

It requires the addition of a direct dependency on a module org.eclipse.jetty.ee10.websocket:jetty-ee10-websocket-jetty-server that is not really described anywhere. The module doesn't have a Readme and the usage / configuration of WS Server using this module is not described in Programming Guide / WS Server.

It seems like there are three approaches to WS Server configuration that are not compatible with each other:

1. Using jetty-${ee-version}-websocket-jakarta-server and JakartaWebSocketServletContainerInitializer
2. Using jetty-websocket-jetty-server and ServerWebSocketContainer
3. Using jetty-${ee-version}-websocket-jetty-server and JettyWebSocketServletContainerInitializer

The third way should be used with Spring 6.1+ and lacks documentation and a section in Programming Guide / WS Server.
It should look something like JettyWebSocketServletContainerInitializer.configure(servletContextHandler, null)

Context

I am migrating a server built with Spring 6.0 and embedded Jetty 11 that uses Jetty WebSocket APIs. It initializing them with
ServerWebSocketContainer#ensure() from the second approach outlined above. After migration to Spring 6.1, I'm facing

Caused by: java.lang.ClassCastException: class org.eclipse.jetty.websocket.server.ServerWebSocketContainer cannot be cast to class org.eclipse.jetty.ee10.websocket.server.JettyWebSocketServerContainer (org.eclipse.jetty.websocket.server.ServerWebSocketContainer and org.eclipse.jetty.ee10.websocket.server.JettyWebSocketServerContainer are in unnamed module of loader 'app')
	at org.eclipse.jetty.ee10.websocket.server.JettyWebSocketServerContainer.getContainer(JettyWebSocketServerContainer.java:63) ~[jetty-ee10-websocket-jetty-server-12.0.16.jar:12.0.16]

which leads me to a lacking documentation around JettyWebSocketServerContainer and jetty-ee10-websocket-jetty-server.
For example, I don't understand what I change by replacing ServerWebSocketContainer#ensure() with JettyWebSocketServletContainerInitializer.configure(servletContextHandler, null). Are these two implementations fully compatible, and what's the difference?

[lachlan-roberts]

For example, I don't understand what I change by replacing ServerWebSocketContainer#ensure() with JettyWebSocketServletContainerInitializer.configure(servletContextHandler, null). Are these two implementations fully compatible, and what's the difference?

They are not fully compatible.

The jetty-ee10-websocket-jetty-server depends on the Servlet API, while jetty-websocket-jetty-server is completely independant of the Servlet API and uses Jetty Core APIs.

• In jetty-ee10-websocket-jetty-server upgrades are done though either a JettyWebSocketServlet or WebSocketUpgradeFilter depending on how its configured. During the WebSocket negotiation you also get special request and response objects which defer to the HttpServletRequest/HttpServletResponse instead of going directly to the core Jetty request/response.
• In jetty-websocket-jetty-server upgrades are done though a core Jetty Handler.

But I agree that this needs better documentation.