Issue #5229 - WebSocket documentation. #6623
Conversation
WebSocket server documentation. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
|
just working out why PRs are not building atm... |
There was a problem hiding this comment.
You might also want to write about the JettyWebSocketCreator class which can be registered to pathspec and can be used to dynamically create the endpoint using information from the request and response.
Also maybe some information about the JettyWebSocketServerContainer.upgrade() feature which allows an upgrade directly without registering a mapping.
...umentation/src/main/asciidoc/programming-guide/server/websocket/server-websocket-filter.adoc
Outdated
Show resolved
Hide resolved
...umentation/src/main/asciidoc/programming-guide/server/websocket/server-websocket-filter.adoc
Outdated
Show resolved
Hide resolved
...cumentation/src/main/asciidoc/programming-guide/server/websocket/server-websocket-jetty.adoc
Outdated
Show resolved
Hide resolved
...cumentation/src/main/asciidoc/programming-guide/server/websocket/server-websocket-jetty.adoc
Outdated
Show resolved
Hide resolved
...tty-documentation/src/main/asciidoc/programming-guide/server/websocket/server-websocket.adoc
Outdated
Show resolved
Hide resolved
...-jetty-tests/src/test/java/org/eclipse/jetty/websocket/tests/JettyClientClassLoaderTest.java
Outdated
Show resolved
Hide resolved
...-jetty-tests/src/test/java/org/eclipse/jetty/websocket/tests/JettyClientClassLoaderTest.java
Outdated
Show resolved
Hide resolved
Updates after review. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
There was a problem hiding this comment.
I only looked at the first bit and think it needs a bit of refactoring.
I'll look deeper once @lachlan-roberts has commented.
| [[pg-server-websocket-configure-filter]] | ||
| ==== Advanced `WebSocketUpgradeFilter` Configuration | ||
|
|
||
| The WebSocket ``ServletContainerInitializer``s, namely `JavaxWebSocketServletContainerInitializer` and `JettyWebSocketServletContainerInitializer`, install the `WebSocketUpgradeFilter` to handle HTTP requests that upgrade to WebSocket. |
There was a problem hiding this comment.
This is not correct.
The jetty SCI doesn't add the filter, rather it is added in the addMapping method on the container. Only the javax SCI always adds the filter.
Moreover, the SCIs do a lot more than just install the filter: pools for inflaters, deflaters, buffers; executors; object factory; mappings; contains; lifecycle listeners etc.
The SCIs initialize a lot of machinery and much of it is extensible/configurable to the users so probably should be of note in the "Advanced" documentation. So I think we should open with a full enumeration of the mechanism that need to be initialized and how/where they are.
|
|
||
| The WebSocket ``ServletContainerInitializer``s, namely `JavaxWebSocketServletContainerInitializer` and `JettyWebSocketServletContainerInitializer`, install the `WebSocketUpgradeFilter` to handle HTTP requests that upgrade to WebSocket. | ||
|
|
||
| Typically, the `WebSocketUpgradeFilter` is not present in the `web.xml` configuration, and therefore the WebSocket ``ServletContainerInitializer``s create a new `WebSocketUpgradeFilter` and install it _before_ any other Filter declared in `web.xml`, under the default name of `"org.eclipse.jetty.websocket.servlet.WebSocketUpgradeFilter"` and with path mapping `/*`. |
There was a problem hiding this comment.
Once we have described all the bits that are initialized, then we need subsections saying how each bit of machinery can be customized. The filter being only one of these subsections. We also need to say how pools etc. can be customized/configured/replaced.
There was a problem hiding this comment.
@gregw the machinery can be customized, but without APIs.
It's all relying on some magic "look at this attribute in the context" and the attribute names are based on classes that are not really meant to be exposed in this way, say for example o.e.j.w.core.WebSocketComponents.
I would not document this now, and if people really struggle, then add the docs later.
Updates after review. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
|
@lachlan-roberts @gregw I have updated the documentation, see also my comments about your comments. |
...tty-documentation/src/main/asciidoc/programming-guide/server/websocket/server-websocket.adoc
Outdated
Show resolved
Hide resolved
...entation/src/main/asciidoc/programming-guide/server/websocket/server-websocket-standard.adoc
Outdated
Show resolved
Hide resolved
Updates after review. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
WebSocket server documentation.
Signed-off-by: Simone Bordet simone.bordet@gmail.com