Migrating the WebSocket Transport |
![]() |
Net4j WS 2 separates WebSocket protocol integration from the implementation that performs WebSocket I/O. This article explains how to migrate existing WS and WSS deployments, clients, and Jetty servers to that design. It also identifies the parts that remain compatible so that operators can limit changes to the installations that need them.
Table of Contents
| 1 | Migration Overview | ||
| 2 | Dependencies and Deployment | ||
| 3 | Migrating WebSocket Clients | ||
| 4 | Migrating WebSocket Servers | ||
| 5 | Migrating Security and Proxy Configuration | ||
| 6 | Migration Checklist | ||
| 7 | Troubleshooting | ||
Issue #226 replaces a Jetty-specific transport implementation in the provider-neutral WS bundle with a Net4j framing layer and message-connection providers. The built-in provider uses the JDK WebSocket client. A separate optional bundle adapts Jetty 12 servers. This keeps Jetty server dependencies out of the core client transport and lets applications supply clients with their own TLS, proxy, and authentication policy.
Migrate an installation when it uses the removed Jetty client classes, subclasses or configures the old
Net4jWebSocketServlet, depends on implicit Eclipse proxy discovery, or packages the old Jetty client
dependencies as part of Net4j WS. A server without a Jetty host can keep using the WS acceptor API with its own provider
integration. The WS/WSS URI schemes, named acceptor routing, Net4j channels, and WS/WSS acceptor configuration model
remain. Connector descriptions continue to identify the service endpoint and acceptor route; current descriptions can
additionally select a provider and carry handshake cookies.
The operator-facing before/after differences are:
WebSocketClient with the JDK WebSocket provider. Configure
TLS, proxy selection, and authentication on an application-owned HttpClient when the defaults do not fit.
Net4jWebSocketServlet mapping with an application-owned Jetty 12 server and
context containing a handler returned by JettyWSUtil.
IProxyService lookup with an explicit JDK
ProxySelector and, when needed, Authenticator on the client.
Continue with server deployment, client configuration, TLS setup, and operations and troubleshooting.
Deploy the org.eclipse.net4j.ws feature (or its org.eclipse.net4j.ws bundle) for WS and WSS
connectors and acceptors. It contributes the WS and WSS factories and registers the JDK message-connection provider
under type jdk. A managed container created
with ContainerUtil.createInitializedContainer() receives these contributions through bundle initialization.
Remove the old Jetty EE8 WebSocket client and server dependencies that were required only by the former core WS bundle.
Do not remove Jetty modules that the application independently needs. For a Jetty-hosted endpoint, add the optional
org.eclipse.net4j.ws.jetty.server bundle and compatible Jetty 12 server and WebSocket modules. The
org.eclipse.net4j.ws.jetty.server feature includes both the core WS feature and server adapter. That
adapter bundle requires Jetty 12; it is not a replacement client dependency.
The embedding application now owns the Jetty Server, its connectors and TLS configuration, handler tree,
startup and shutdown. It also owns custom JDK HttpClient instances passed to provider factories. Net4j owns
the connectors and acceptors registered in its managed container.
There is no new XML setting for creating custom JDK clients or embedding the Jetty upgrade handler. Those are Java object configuration tasks; keep XML acceptor declarations where they continue to describe the acceptor. This valid WS acceptor declaration uses the same configuration mechanism as the CDO server configuration:
The JDK provider is selected by default, so a normal WS or WSS connector needs no provider token. Use the utility
methods to construct connector descriptions rather than assembling route paths by hand. A description targets the
named acceptor at the service URI; optional arguments include provider selection and cookie:name=value
handshake cookies. The cookie argument is configuration data, so do not put credentials or session secrets in a
persistent or logged connector description.
The following example creates its own container and connects one WS connector through the default JDK provider. It
closes that connector individually, then deactivates the container it created. For WSS, use the WSS connector factory
through WSSUtil together with a wss URI; changing the URI scheme alone does not select the
secure connector factory.
For a custom TLS trust configuration or proxy policy, register a provider factory configured with a caller-owned
HttpClient in the same container. The example connects a WSS endpoint with the corporate
provider, a bounded timeout, and a handshake cookie, then closes the connector and its privately owned container.
It uses the JDK default trust context; substitute the application's configured trust context when required.
The provider and connector do not close the HttpClient; the application must retain it while any
connector can use it. Java 11's client has no close method; on Java 21 and later, close it only after its connectors
stop. The example marks that version-specific cleanup without making this Java 11 source depend on the newer method.
A connector can be closed without deactivating a shared container. Deactivate a container only when its owner is shutting down the container and all products it manages.
Retain the complete factory description. IConnector.getURL() reports the transport endpoint; for
WS/WSS it omits provider selection and handshake cookies. Reconstructing an equivalent connector from that URL may
silently select the default jdk provider, losing a custom WSS trust configuration. Retain the original
description passed to WSUtil/WSSUtil, or ask the registered connector factory for its
description with IFactory.getDescriptionFor(Object). For example, use the factory for
ConnectorFactory.PRODUCT_GROUP and the WS or WSS factory type selected from the connector's scheme.
The previous Net4jWebSocketServlet and Jetty socket endpoint were removed from the core WS bundle. With
Jetty 12, create an application-owned Server and ContextHandler, then install the returned
upgrade handler before starting the server. Use a mapping such as /net4j/*; the client appends
/@<acceptor-name> to that path. The utility wraps the context's existing application handler and routes
only to the active acceptors passed to it. Both the decoded path suffix and the Net4jAcceptor handshake
header must identify the same route.
The following example creates an initialized Net4j container and named WS acceptor, installs the adapter in an application-owned Jetty server/context, starts the server, and connects a bounded-timeout client. The adapter only creates the upgrade handler; the application starts and stops Jetty. It closes the individual client connector, stops Jetty, then deactivates the acceptor and the privately owned container. A host with a shared container should close the connector and acceptor as appropriate but leave container shutdown to its owner. WSS uses the same integration with a WSS acceptor, a WSS connector, and an application-configured HTTPS server connector.
Configure TLS at the layer that owns the connection. A WSS client can use the default JDK TLS context, or a custom
SSLContext configured with the application's trust material. The JDK provider keeps normal certificate
chain and hostname verification enabled. Never work around trust failures by disabling verification. A Jetty-hosted
WSS endpoint uses the TLS configuration of the application's HTTPS server connector; the Net4j adapter does not create
or own TLS connectors.
HTTP origin authentication and proxy authentication belong in the caller-configured HttpClient, typically
through its Authenticator, ProxySelector, and TLS settings. WS transport no longer discovers
Eclipse IProxyService implicitly. Applications that relied on Eclipse proxy preferences must translate
the required policy into JDK client configuration and register a provider factory with that client.
For an HTTP CONNECT proxy, configure a proxy selector and an authenticator for proxy credentials. The JDK normally
disables Basic authentication for HTTP CONNECT tunneling. Enabling it with
-Djdk.http.auth.tunneling.disabledSchemes= changes JVM-wide behavior and can expose credentials to
untrusted proxies; use it only after reviewing the security consequences and the proxy trust boundary. Prefer a proxy
authentication scheme supported by the JDK without that override.
Work through this sequence for each client or server installation:
org.eclipse.net4j.ws bundle. Remove Jetty EE8 client dependencies that
existed only for the former Net4j WS implementation.
JettyWSUtil.createUpgradeHandler, and ensure each route matches the URI scheme and TLS state.
Missing provider factory: check that the org.eclipse.net4j.ws bundle is resolved and its factories
are initialized in the same managed container that creates the connector. For a custom provider, register its factory
before connector creation and ensure the provider: token exactly matches the registered type.
HTTP upgrade or routing rejection: verify the path mapping covers the service path and appended
/@name route, the acceptor is active and registered under that name, and the handshake header and route
agree. A request rejected with 404 commonly indicates a missing or mismatched route; 403 commonly indicates that the
request's secure state does not match the WS/WSS acceptor.
TLS certificate validation failure: check the server certificate chain, the hostname in the service URI, and the trust material used by the client provider. Keep hostname and certificate verification enabled.
Authenticated proxy failure: ensure the caller-configured client actually selects the proxy and its authenticator supplies credentials for that proxy. If the proxy requires Basic CONNECT authentication, account for the JDK's disabled-by-default behavior and assess the JVM-wide property before enabling it.
Leaked or prematurely closed connections: the Net4j container owns connectors and acceptors, while the
application owns custom HttpClient and Jetty server lifecycles. Stop connectors before closing a shared
client, deactivate the container during shutdown, and stop the Jetty server through the application's lifecycle.