WebSocket Server

Jetty provides different implementations of the WebSocket protocol:

The Jakarta EE implementations and APIs are described in this section.

Using the standard Jakarta EE WebSocket APIs allows your applications to depend only on standard APIs, and your applications may be deployed in any compliant WebSocket Container that supports Jakarta WebSocket. The standard Jakarta EE WebSocket APIs provide these features that are not present in the Jetty WebSocket APIs:

  • Encoders and Decoders for automatic conversion of text or binary messages to objects.

The Jetty specific WebSocket implementation and APIs are described in this section.

Using the Jetty WebSocket APIs allows your applications to be more efficient and offer greater and more fine-grained control, and provide these features that are not present in the Jakarta EE WebSocket APIs:

  • A demand mechanism to control backpressure.

  • Remote socket address (IP address and port) information.

  • Advanced request URI matching with regular expressions, in addition to Servlet patterns and URI template patterns.

  • More configuration options, for example the network buffer capacity.

  • Programmatic WebSocket upgrade, in addition to WebSocket upgrade based on URI matching, for maximum flexibility.

If your application needs specific features that are not provided by the standard APIs, the Jetty WebSocket APIs may provide such features.

If the feature you are looking for is not present, you may ask for these features by submitting an issue to the Jetty Project without waiting for the standard Jakarta EE process to approve them and release a new version of the Jakarta EE WebSocket specification.

Standard APIs Implementation

When you write a WebSocket application using the standard jakarta.websocket APIs, your code typically need to depend on just the APIs to compile your application. However, at runtime you need to have an implementation of the standard APIs in your class-path (or module-path).

The standard jakarta.websocket APIs, for example for Jakarta EE 10, are provided by the following Maven artifact:

<dependency>
  <groupId>jakarta.websocket</groupId>
  <artifactId>jakarta.websocket-api</artifactId>
  <version>2.1.0</version>
</dependency>

At runtime, you also need an implementation of the standard Jakarta EE 10 WebSocket APIs, that Jetty provides with the following Maven artifact (and its transitive dependencies):

<dependency>
  <groupId>org.eclipse.jetty.ee10.websocket</groupId>
  <artifactId>jetty-ee10-websocket-jakarta-server</artifactId>
  <version>12.0.15-SNAPSHOT</version>
</dependency>

The jakarta.websocket-api artifact and the jetty-ee10-websocket-jakarta-server artifact (and their transitive dependencies) should be present in the server class-path (or module-path), and never in the web application’s /WEB-INF/lib directory.

To configure correctly your WebSocket application based on the standard Jakarta EE 10 WebSocket APIs, you need two steps:

  1. Make sure that Jetty sets up an instance of jakarta.websocket.server.ServerContainer, described in this section.

  2. Configure the WebSocket endpoints that implement your application logic, either by annotating their classes with the standard jakarta.websocket annotations, or by using the ServerContainer APIs to register them in your code, described in this section.

Setting Up ServerContainer

Jetty sets up a ServerContainer instance using JakartaWebSocketServletContainerInitializer.

When you deploy web applications using WebAppContext, then JakartaWebSocketServletContainerInitializer is automatically discovered and initialized by Jetty when the web application starts, so that it sets up the ServerContainer. In this way, you do not need to write any additional code:

// Create a Server with a ServerConnector listening on port 8080.
Server server = new Server(8080);

// Create a WebAppContext with the given context path.
WebAppContext handler = new WebAppContext("/path/to/webapp", "/ctx");
server.setHandler(handler);

// Starting the Server will start the WebAppContext.
server.start();

On the other hand, when you deploy web applications using ServletContextHandler, you have to write the code to ensure that the JakartaWebSocketServletContainerInitializer is initialized, so that it sets up the ServerContainer:

// Create a Server with a ServerConnector listening on port 8080.
Server server = new Server(8080);

// Create a ServletContextHandler with the given context path.
ServletContextHandler handler = new ServletContextHandler("/ctx");
server.setHandler(handler);

// Ensure that JavaxWebSocketServletContainerInitializer is initialized,
// to setup the ServerContainer for this web application context.
JakartaWebSocketServletContainerInitializer.configure(handler, null);

// Starting the Server will start the ServletContextHandler.
server.start();

Calling JakartaWebSocketServletContainerInitializer.configure(...) must be done before the ServletContextHandler is started, and configures the Jakarta EE 10 WebSocket implementation for that web application context, making ServerContainer available to web applications.

Configuring Endpoints

Once you have setup the ServerContainer, you can configure your WebSocket endpoints.

The WebSocket endpoints classes may be either annotated with the standard jakarta.websocket annotations, extend the jakarta.websocket.Endpoint abstract class, or implement the jakarta.websocket.server.ServerApplicationConfig interface.

When you deploy web applications using WebAppContext, then annotated WebSocket endpoint classes are automatically discovered and registered. In this way, you do not need to write any additional code; you just need to ensure that your WebSocket endpoint classes are present in the web application’s /WEB-INF/classes directory, or in a *.jar file in /WEB-INF/lib.

On the other hand, when you deploy web applications using WebAppContext but you need to perform more advanced configuration of the ServerContainer or of the WebSocket endpoints, or when you deploy web applications using ServletContextHandler, you need to access the ServerContainer APIs.

The ServerContainer instance is stored as a ServletContext attribute, so it can be retrieved when the ServletContext is initialized, either from a ServletContextListener, or from a Servlet Filter, or from an HttpServlet:

// Create a Server with a ServerConnector listening on port 8080.
Server server = new Server(8080);

// Create a ServletContextHandler with the given context path.
ServletContextHandler handler = new ServletContextHandler("/ctx");
server.setHandler(handler);

// Ensure that JavaxWebSocketServletContainerInitializer is initialized,
// to setup the ServerContainer for this web application context.
JakartaWebSocketServletContainerInitializer.configure(handler, null);

// Add a WebSocket-initializer Servlet to register WebSocket endpoints.
handler.addServlet(MyJavaxWebSocketInitializerServlet.class, "/*");

// Starting the Server will start the ServletContextHandler.
server.start();
public class MyJavaxWebSocketInitializerServlet extends HttpServlet
{
    @Override
    public void init() throws ServletException
    {
        try
        {
            // Retrieve the ServerContainer from the ServletContext attributes.
            ServerContainer container = (ServerContainer)getServletContext().getAttribute(ServerContainer.class.getName());

            // Configure the ServerContainer.
            container.setDefaultMaxTextMessageBufferSize(128 * 1024);

            // Simple registration of your WebSocket endpoints.
            container.addEndpoint(MyJavaxWebSocketEndPoint.class);

            // Advanced registration of your WebSocket endpoints.
            container.addEndpoint(
                ServerEndpointConfig.Builder.create(MyJavaxWebSocketEndPoint.class, "/ws")
                    .subprotocols(List.of("my-ws-protocol"))
                    .build()
            );
        }
        catch (DeploymentException x)
        {
            throw new ServletException(x);
        }
    }
}

When you deploy web applications using ServletContextHandler, you can alternatively use the code below to set up the ServerContainer and configure the WebSocket endpoints in one step:

// Create a Server with a ServerConnector listening on port 8080.
Server server = new Server(8080);

// Create a ServletContextHandler with the given context path.
ServletContextHandler handler = new ServletContextHandler("/ctx");
server.setHandler(handler);

// Setup the ServerContainer and the WebSocket endpoints for this web application context.
JakartaWebSocketServletContainerInitializer.configure(handler, (servletContext, container) ->
{
    // Configure the ServerContainer.
    container.setDefaultMaxTextMessageBufferSize(128 * 1024);

    // Simple registration of your WebSocket endpoints.
    container.addEndpoint(MyJavaxWebSocketEndPoint.class);

    // Advanced registration of your WebSocket endpoints.
    container.addEndpoint(
        ServerEndpointConfig.Builder.create(MyJavaxWebSocketEndPoint.class, "/ws")
            .subprotocols(List.of("my-ws-protocol"))
            .build()
    );
});

// Starting the Server will start the ServletContextHandler.
server.start();

When the ServletContextHandler is started, the Configurator lambda (the second parameter passed to JakartaWebSocketServletContainerInitializer.configure(...)) is invoked and allows you to explicitly configure the WebSocket endpoints using the standard APIs provided by ServerContainer.

Upgrade to WebSocket

Under the hood, JakartaWebSocketServletContainerInitializer installs the org.eclipse.jetty.ee10.websocket.servlet.WebSocketUpgradeFilter, which is the component that intercepts HTTP requests to upgrade to WebSocket, and performs the upgrade from the HTTP protocol to the WebSocket protocol.

The WebSocketUpgradeFilter is installed under the filter name corresponding to its class name (that is, the string "org.eclipse.jetty.ee10.websocket.servlet.WebSocketUpgradeFilter") and with a filter mapping of /*.

Refer to the advanced WebSocketUpgradeFilter configuration section for more information.

With the default configuration, every HTTP request flows first through the WebSocketUpgradeFilter.

If the HTTP request is a valid upgrade to WebSocket, then WebSocketUpgradeFilter tries to find a matching WebSocket endpoint for the request URI path; if the match is found, WebSocketUpgradeFilter performs the upgrade and does not invoke any other Filter or Servlet. From this point on, the communication happens with the WebSocket protocol, and HTTP components such as Filters and Servlets are not relevant anymore.

If the HTTP request is not an upgrade to WebSocket, or WebSocketUpgradeFilter did not find a matching WebSocket endpoint for the request URI path, then the request is passed to the Filter chain of your web application, and eventually the request arrives to a Servlet to be processed (otherwise a 404 Not Found response is returned to client).

Advanced WebSocketUpgradeFilter Configuration

The WebSocketUpgradeFilter that handles the HTTP requests that upgrade to WebSocket is installed by the JakartaWebSocketServletContainerInitializer, as described in this section.

Typically, the WebSocketUpgradeFilter is not present in the web.xml configuration, and therefore the mechanisms above create a new WebSocketUpgradeFilter and install it before any other Filter declared in web.xml, under the default name of "org.eclipse.jetty.ee10.websocket.servlet.WebSocketUpgradeFilter" and with path mapping /*.

However, if the WebSocketUpgradeFilter is already present in web.xml under the default name, then the ServletContainerInitializers will use that declared in web.xml instead of creating a new one.

This allows you to customize:

  • The filter order; for example, by configuring filters for increased security or authentication before the WebSocketUpgradeFilter.

  • The WebSocketUpgradeFilter configuration via init-params, that affects all Session instances created by this filter.

  • The WebSocketUpgradeFilter path mapping. Rather than the default mapping of /*, you can map the WebSocketUpgradeFilter to a more specific path such as /ws/*.

  • The possibility to have multiple WebSocketUpgradeFilters, mapped to different paths, each with its own configuration.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
         version="5.0">
  <display-name>My WebSocket WebApp</display-name>

  <!-- The SecurityFilter *must* be the first --> (1)
  <filter>
    <filter-name>security</filter-name>
    <filter-class>com.acme.SecurityFilter</filter-class>
    <async-supported>true</async-supported>
  </filter>
  <filter-mapping>
    <filter-name>security</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

  <!-- Configure the default WebSocketUpgradeFilter --> (2)
  <filter>
    <!-- The filter name must be the default WebSocketUpgradeFilter name -->
    <filter-name>org.eclipse.jetty.ee10.websocket.servlet.WebSocketUpgradeFilter</filter-name> (3)
    <filter-class>org.eclipse.jetty.ee10.websocket.servlet.WebSocketUpgradeFilter</filter-class>
    <!-- Configure at most 1 MiB text messages -->
    <init-param> (4)
      <param-name>maxTextMessageSize</param-name>
      <param-value>1048576</param-value>
    </init-param>
    <async-supported>true</async-supported>
  </filter>
  <filter-mapping>
    <filter-name>org.eclipse.jetty.ee10.websocket.servlet.WebSocketUpgradeFilter</filter-name>
    <!-- Use a more specific path mapping for WebSocket requests -->
    <url-pattern>/ws/*</url-pattern> (5)
  </filter-mapping>

</web-app>
1 The custom SecurityFilter is the first, to apply custom security.
2 The configuration for the default WebSocketUpgradeFilter.
3 Note the use of the default WebSocketUpgradeFilter name.
4 Specific configuration for WebSocketUpgradeFilter parameters.
5 Use a more specific path mapping for WebSocketUpgradeFilter.

Note that using a more specific path mapping for WebSocket requests is also beneficial to the performance of normal HTTP requests: they do not go through the WebSocketUpgradeFilter (as they will not match its path mapping), saving the cost of analyzing them to see whether they are WebSocket upgrade requests or not.

Jetty APIs Implementation

When you write a WebSocket application using the Jetty WebSocket APIs, your code typically needs to depend on just the Jetty WebSocket APIs to compile your application. However, at runtime you need to have the implementation of the Jetty WebSocket APIs in your class-path (or module-path).

Jetty’s WebSocket APIs are provided by the following Maven artifact:

<dependency>
  <groupId>org.eclipse.jetty.websocket</groupId>
  <artifactId>jetty-websocket-jetty-api</artifactId>
  <version>12.0.15-SNAPSHOT</version>
</dependency>

Jetty’s implementation of the Jetty WebSocket APIs is provided by the following Maven artifact (and its transitive dependencies):

<dependency>
  <groupId>org.eclipse.jetty.websocket</groupId>
  <artifactId>jetty-websocket-jetty-server</artifactId>
  <version>12.0.15-SNAPSHOT</version>
</dependency>

The jetty-websocket-jetty-api artifact and the jetty-websocket-jetty-server artifact (and its transitive dependencies) should be present in the server class-path (or module-path), and never in a web application’s /WEB-INF/lib directory.

To configure correctly your WebSocket application based on the Jetty WebSocket APIs, you need two steps:

  1. Make sure to set up an instance of org.eclipse.jetty.websocket.server.ServerWebSocketContainer.

  2. Use the ServerWebSocketContainer APIs in your applications to register the WebSocket endpoints that implement your application logic.

You can read more about the Jetty WebSocket architecture, which is common to both client-side and server-side, to get familiar with the terminology used in the following sections.

Setting up ServerWebSocketContainer

You need Jetty to set up a ServerWebSocketContainer instance to make your WebSocket applications based on the Jetty WebSocket APIs work.

Your WebSocket web application is represented by a ContextHandler. The WebSocket upgrade is performed in a descendant (typically the only child) of the ContextHandler, either by the org.eclipse.jetty.websocket.server.WebSocketUpgradeHandler, or by a custom Handler that you write and is part of your web application.

In both cases, you need to set up a ServerWebSocketContainer, and this can be done implicitly by using WebSocketUpgradeHandler, or explicitly by creating the ServerWebSocketContainer instance.

Implicit setup using WebSocketUpgradeHandler

Using WebSocketUpgradeHandler is the most common way to set up your WebSocket applications.

You can use the WebSocketUpgradeHandler and the ServerWebSocketContainer APIs to map HTTP request URIs to WebSocket endpoints.

When an HTTP request arrives, WebSocketUpgradeHandler tests whether it is a WebSocket upgrade request, whether it matches a mapped URI, and if so upgrades the protocol to WebSocket.

From this point on, the communication on the upgraded connection happens with the WebSocket protocol. This is very similar to what WebSocketUpgradeFilter does when using the Jakarta EE WebSocket APIs.

Once you have set up the WebSocketUpgradeHandler, you can use the ServerWebSocketContainer APIs to configure the WebSocket endpoints. The example below shows how to set up the WebSocketUpgradeHandler and use the ServerWebSocketContainer APIs:

// Create a Server with a ServerConnector listening on port 8080.
Server server = new Server(8080);

// Create a ContextHandler with the given context path.
ContextHandler contextHandler = new ContextHandler("/ctx");
server.setHandler(contextHandler);

// Create a WebSocketUpgradeHandler that implicitly creates a ServerWebSocketContainer.
WebSocketUpgradeHandler webSocketHandler = WebSocketUpgradeHandler.from(server, contextHandler, container ->
{
    // Configure the ServerWebSocketContainer.
    container.setMaxTextMessageSize(128 * 1024);

    // Map a request URI to a WebSocket endpoint, for example using a regexp.
    container.addMapping("regex|/ws/v\\d+/echo", (rq, rs, cb) -> new EchoEndPoint());

    // Advanced registration of a WebSocket endpoint.
    container.addMapping("/ws/adv", (rq, rs, cb) ->
    {
        List<String> subProtocols = rq.getSubProtocols();
        if (subProtocols.contains("my-ws-protocol"))
            return new MyJettyWebSocketEndPoint();
        return null;
    });
});
contextHandler.setHandler(webSocketHandler);

// Starting the Server will start the ContextHandler and the WebSocketUpgradeHandler,
// which would run the configuration of the ServerWebSocketContainer.
server.start();

The mapping of request URIs to WebSocket endpoints is further explained in this section.

Explicit setup using ServerWebSocketContainer

A more advanced way to set up your WebSocket applications is to explicitly create the ServerWebSocketContainer instance programmatically.

This gives you more flexibility when deciding whether an HTTP request should be upgraded to WebSocket, because you do not need to match request URIs (although you can), nor you need to use WebSocketUpgradeHandler (although you can).

Once you have created the ServerWebSocketContainer, you can use its APIs to configure the WebSocket endpoints as shown in the example below.

// Create a Server with a ServerConnector listening on port 8080.
Server server = new Server(8080);

// Create a ContextHandler with the given context path.
ContextHandler contextHandler = new ContextHandler("/ctx");
server.setHandler(contextHandler);

// Create a ServerWebSocketContainer, which is also stored as an attribute in the context.
ServerWebSocketContainer container = ServerWebSocketContainer.ensure(server, contextHandler);

// You can use WebSocketUpgradeHandler if you want, but it is not necessary.
// You can ignore the line below, it is shown only for reference.
WebSocketUpgradeHandler webSocketHandler = new WebSocketUpgradeHandler(container);

// You can directly use ServerWebSocketContainer from any Handler.
contextHandler.setHandler(new Handler.Abstract()
{
    @Override
    public boolean handle(Request request, Response response, Callback callback)
    {
        // Retrieve the ServerWebSocketContainer.
        ServerWebSocketContainer container = ServerWebSocketContainer.get(request.getContext());

        // Verify special conditions for which a request should be upgraded to WebSocket.
        String pathInContext = Request.getPathInContext(request);
        if (pathInContext.startsWith("/ws/echo") && request.getHeaders().contains("X-WS", "true"))
        {
            try
            {
                // This is a WebSocket upgrade request, perform a direct upgrade.
                boolean upgraded = container.upgrade((rq, rs, cb) -> new EchoEndPoint(), request, response, callback);
                if (upgraded)
                    return true;
                // This was supposed to be a WebSocket upgrade request, but something went wrong.
                Response.writeError(request, response, callback, HttpStatus.UPGRADE_REQUIRED_426);
                return true;
            }
            catch (Exception x)
            {
                Response.writeError(request, response, callback, HttpStatus.UPGRADE_REQUIRED_426, "failed to upgrade", x);
                return true;
            }
        }
        else
        {
            // Handle a normal HTTP request.
            response.setStatus(HttpStatus.OK_200);
            callback.succeeded();
            return true;
        }
    }
});

// Starting the Server will start the ContextHandler.
server.start();

Note how the call to ServerWebSocketContainer.upgrade(...) allows you to perform a direct WebSocket upgrade programmatically.

WebSocket Endpoints

When using the Jetty WebSocket APIs, the WebSocket endpoint classes must be either annotated with the Jetty WebSocket annotations from the org.eclipse.jetty.websocket.api.annotations package, or implement the org.eclipse.jetty.websocket.api.Session.Listener interface.

In the case you want to implement the Session.Listener interface, remember that you have to explicitly demand to receive the next WebSocket event. Use Session.Listener.AutoDemanding to automate the demand for simple use cases.

Refer to the Jetty WebSocket architecture section for more information about Jetty WebSocket endpoints and how to correctly deal with the demand for WebSocket events.

There is no automatic discovery of WebSocket endpoints; all the WebSocket endpoints of your application must be returned by a org.eclipse.jetty.websocket.server.WebSocketCreator that is either mapped to a request URI via ServerWebSocketContainer.addMapping(...), or directly upgraded via ServerWebSocketContainer.upgrade(...).

In the call to ServerWebSocketContainer.addMapping(...), you can specify a path spec (the first parameter) that can specified as discussed in this section.

When the Server is started, the lambda passed to ServerWebSocketContainer.configure(...)) is invoked and allows you to explicitly configure the WebSocket endpoints using the Jetty WebSocket APIs provided by ServerWebSocketContainer.

Custom PathSpec Mappings

The ServerWebSocketContainer.addMapping(...) API maps a path spec to a WebSocketCreator instance (typically a lambda expression). The path spec is matched against the WebSocket upgrade request URI to select the correspondent WebSocketCreator to invoke.

The path spec can have these forms:

  • Servlet syntax, specified with servlet|<path spec>, where the servlet| prefix can be omitted if the path spec begins with / or *. (for example, /ws, /ws/chat or *.ws).

  • Regex syntax, specified with regex|<path spec>, where the regex| prefix can be omitted if the path spec begins with ^ (for example, ^/ws/[0-9]+).

  • URI template syntax, specified with uri-template|<path spec> (for example uri-template|/ws/chat/{room}).

Within the WebSocketCreator, it is possible to access the path spec and, for example in case of URI templates, extract additional information in the following way:

Server server = new Server(8080);

ContextHandler contextHandler = new ContextHandler("/ctx");
server.setHandler(contextHandler);

// Create a WebSocketUpgradeHandler.
WebSocketUpgradeHandler webSocketHandler = WebSocketUpgradeHandler.from(server, contextHandler, container ->
{
    container.addMapping("/ws/chat/{room}", (upgradeRequest, upgradeResponse, callback) ->
    {
        // Retrieve the URI template.
        UriTemplatePathSpec pathSpec = (UriTemplatePathSpec)upgradeRequest.getAttribute(PathSpec.class.getName());

        // Match the URI template.
        String pathInContext = Request.getPathInContext(upgradeRequest);
        Map<String, String> params = pathSpec.getPathParams(pathInContext);
        String room = params.get("room");

        // Create the new WebSocket endpoint with the URI template information.
        return new MyWebSocketRoomEndPoint(room);
    });
});
contextHandler.setHandler(webSocketHandler);