Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added WebSocket migration documentation, pointing to existing WebSock… #10542

Merged
merged 3 commits into from
Sep 20, 2023
Merged

Added WebSocket migration documentation, pointing to existing WebSock… #10542

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
11e13d9
Added WebSocket migration documentation, pointing to existing WebSock…
sbordet Sep 18, 2023
de27fad
Merged branch 'jetty-12.0.x' into 'fix/jetty-12-websocket-migration-d…
sbordet Sep 18, 2023
5edc018
Updates from review.
sbordet Sep 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 29 additions & 4 deletions ...mentation/src/main/asciidoc/programming-guide/migration/migration-11-to-12.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down Expand Up @@ -147,14 +153,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.
sbordet marked this conversation as resolved.
Show resolved Hide resolved
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.