Added WebSocket migration documentation, pointing to existing WebSock… (

#10542)

* Added WebSocket migration documentation, pointing to existing WebSocket documentation.

Signed-off-by: Simone Bordet <[email protected]>

documentation/jetty-documentation/src/main/asciidoc/programming-guide/migration/migration-11-to-12.adoc

@@ -92,6 +92,12 @@
 | `org.eclipse.jetty.client.**util**.*` | `org.eclipse.jetty.client.*`
 | `org.eclipse.jetty.client.**http**.*` | `org.eclipse.jetty.client.**transport**.*`
 | `org.eclipse.jetty.http2.client.**http**.*` | `org.eclipse.jetty.http2.client.**transport**.*`
+
+| `org.eclipse.jetty.websocket.api.annotation.**OnWebSocketConnect**` | `org.eclipse.jetty.websocket.api.annotation.**OnWebSocketOpen**`
+| `org.eclipse.jetty.websocket.api.**WriteCallback**` | `org.eclipse.jetty.websocket.api.**Callback**`
+| `org.eclipse.jetty.websocket.api.**WebSocket*Listener**` | `org.eclipse.jetty.websocket.api.**Session.Listener.AutoDemanding**`
+| `org.eclipse.jetty.websocket.api.**RemoteEndpoint**` | `org.eclipse.jetty.websocket.api.**Session**`
+| `org.eclipse.jetty.websocket.api.**WebSocketPolicy**` | `org.eclipse.jetty.websocket.api.**Configurable**`
 |===
 
 [[pg-migration-11-to-12-servlet-to-handler]]
@@ -148,14 +154,33 @@ include::../{doc_code}/org/eclipse/jetty/docs/programming/migration/ServletToHan
 [[pg-migration-11-to-12-api-changes]]
 ==== APIs Changes
 
-===== `jetty-client`
+===== `HttpClient`
 
-`Request.onResponseContentDemanded(Response.DemandedContentListener)` has been replaced by `Request.onResponseContentSource(Response.ContentSourceListener)`.
+The Jetty 11 `Request.onResponseContentDemanded(Response.DemandedContentListener)` API has been replaced by `Request.onResponseContentSource(Response.ContentSourceListener)` in Jetty 12.
 
 However, also look at `Request.onResponseContentAsync(Response.AsyncContentListener)` and `Request.onResponseContent(Response.ContentListener)` for simpler usages.
 
-The old model was a "demand+push" model: the application was demanding content; when the content was available, the implementation was pushing content to the application by calling `DemandedContentListener.onContent(Response, LongConsumer, ByteBuffer, Callback)` for every content chunk.
+The Jetty 11 model was a "demand+push" model: the application was demanding content; when the content was available, the implementation was pushing content to the application by calling `DemandedContentListener.onContent(Response, LongConsumer, ByteBuffer, Callback)` for every content chunk.
 
-The new model is a "demand+pull" model: when the content is available, the implementation calls once `Response.ContentSourceListener.onContentSource(Content.Source)`; the application can then pull the content chunks from the `Content.Source`.
+The Jetty 12 model is a "demand+pull" model: when the content is available, the implementation calls once `Response.ContentSourceListener.onContentSource(Content.Source)`; the application can then pull the content chunks from the `Content.Source`.
 
 For more information about the new model, see xref:pg-arch-io-content-source[this section].
+
+===== WebSocket
+
+The Jetty WebSocket APIs have been vastly simplified, and brought in line with the style of other APIs.
+
+The Jetty 12 WebSocket APIs are now fully asynchronous, so the Jetty 11 `SuspendToken` class has been removed in favor of an explicit (or automatic) demand mechanism in Jetty 12 (for more information, refer to xref:pg-websocket-endpoints-demand[this section]).
+
+The various Jetty 11 `WebSocket*Listener` interfaces have been replaced by a single interface in Jetty 12, `Session.Listener.AutoDemanding` (for more information, refer to xref:pg-websocket-endpoints-listener[this section]).
+
+The Jetty 11 `RemoteEndpoint` APIs have been merged into the `Session` APIs in Jetty 12.
+
+The Jetty 11 `WriteCallback` class has been renamed to just `Callback` in Jetty 12, because it is now also used when receiving binary data.
+Note that this `Callback` interface is a different interface from the `org.eclipse.jetty.util.Callback` interface, which cannot be used in the Jetty WebSocket APIs due to class loader visibility issues.
+
+On the server-side, the Jetty WebSocket APIs have been made independent of the Servlet APIs.
+
+Jetty 11 `JettyWebSocketServerContainer` has been replaced by `ServerWebSocketContainer` in Jetty 12, with similar APIs (for more information, refer to xref:pg-server-websocket-jetty[this section]).
+
+On the client-side the `WebSocketClient` APIs are practically unchanged, as most of the changes come from the `HttpClient` changes described above.