Jakarta WebSocket Specification

A logical WebSocket endpoint is represented in the Jakarta WebSocket API by instances of the Endpoint class. Developers may subclass the Endpoint class with a public, concrete class in order to intercept lifecycle events of the endpoint: those of a peer connecting, an open connection ending and an error being raised during the lifetime of the endpoint.

Unless otherwise overridden by a developer provided configurator (see Section 3.1.7), the WebSocket implementation must use one instance per application per VM of the Endpoint class to represent the logical endpoint per connected peer [WSC 2.1.1-1]. Each instance of the Endpoint class in this typical case only handles connections to the endpoint from one and only one peer.

The Jakarta WebSocket API models the sequence of interactions between an endpoint and each of its peers using an instance of the Session class. The interactions between a peer and an endpoint begin with an open notification, followed by some number, possibly zero, of WebSocket messages between the endpoint and peer, followed by a close notification or possibly a fatal error which terminates the connection. For each peer that is interacting with an endpoint, there is one unique Session instance that represents that interaction [WSC 2.1.2-1]. This Session instance corresponding to the connection with that peer is passed to the endpoint instance representing the logical endpoint at the key events in its lifecycle.

Developers may use the user property map accessible through the getUserProperties() call on the Session object to associate application specific information with a particular session. The WebSocket implementation must preserve this session data for later access until the completion of the onClose() method on the endpoint instance [WSC 2.1.2-2]. After that time, the WebSocket implementation is permitted to discard the developer data. A WebSocket implementation that chooses to pool Session instances may at that point re-use the same Session instance to represent a new connection provided it issues a new unique Session id [WSC 2.1.2-3].

WebSocket implementations that are part of a distributed container may need to migrate WebSocket sessions from one node to another in the case of a failover. Implementations are required to preserve developer data objects inserted into the WebSocket session if the data is marked java.io.Serializable [WSC 2.1.2-4].

The Jakarta WebSocket API presents a variety of means for an endpoint to receive messages from its peers. Developers implement the subtype of the MessageHandler interface with the message delivery style that best suits their needs, and register the interest in messages from a particular peer by registering the handler on the Session instance corresponding to the peer.

The API limits the registration of MessageHandlers per Session to be one MessageHandler per native WebSocket message type [WSC 2.1.3-1]. In other words, the developer can only register at most one MessageHandler for incoming text messages, one MessageHandler for incoming binary messages, and one MessageHandler for incoming pong messages. The WebSocket implementation must generate an error if this restriction is violated [WSC 2.1.3-2].

Future versions of the specification may lift this restriction.

Method Session.addMessageHandler(MessageHandler) is not safe for use in all circumstances, especially when using Lambda Expressions. The API forces implementations to get the MessageHandler’s type parameter in runtime, which is not always possible. The only case where you can safely use this method is when you are directly implementing MessageHandler.Whole or MessageHandler.Partial as an anonymous class. This approach guarantees that generic type information will be present in the generated class file and the runtime will be able to get it. For any other case (Lambda Expressions included), one of following methods have to be used: Session.addMessageHandler(Class<T>, MessageHandler.Partial<T>) or Session.addMessageHandler(Class<T>, MessageHandler.Whole<T>).

The Jakarta WebSocket API models each peer of a session with an endpoint as an instance of the RemoteEndpoint interface. This interface and its two subtypes (RemoteEndpoint.Whole and RemoteEndpoint.Partial) contain a variety of methods for sending WebSocket messages from the endpoint to its peer.

Here is an example of a server endpoint that waits for incoming text messages, and responds immediately when it gets one to the client that sent it. The example endpoint is shown, first using only the API classes:

and second using the annotations in the API:

Note: The examples are almost equivalent save for the annotated endpoint carries its own path mapping.

If an open connection to a WebSocket endpoint is to be closed for any reason, whether as a result of receiving a WebSocket close event from the peer, or because the underlying implementation has reason to close the connection, the WebSocket implementation must invoke the onClose() method of the WebSocket endpoint [WSC 2.1.5-1].

If the close was initiated by the remote peer, the implementation must use the close code and reason sent in the WebSocket protocol close frame. If the close was initiated by the local container, for example if the local container determines the session has timed out, the local implementation must use the WebSocket protocol close code 1006 (a code especially disallowed in close frames on the wire), with a suitable close reason. That way the endpoint can determine whether the close was initiated remotely or locally. If the session is closed locally, the implementation must attempt to send the WebSocket close frame prior to calling the onClose() method of the WebSocket endpoint.

The WebSocket protocol is a two-way protocol. Once established, the WebSocket protocol is symmetrical between the two parties in the conversation. The difference between a WebSocket client and a WebSocket server lies only in the means by which the two parties are connected. In this specification, we will say that a WebSocket client is a WebSocket endpoint that initiates a connection to a peer. We will say that a WebSocket server is a WebSocket endpoint that is published and awaits connections from peers. In most deployments, a WebSocket client will connect to only one WebSocket server, and a WebSocket server will accept connections from several clients.

Accordingly, the WebSocket API only distinguishes between endpoints that are WebSocket clients from endpoints that are WebSocket servers in the configuration and setup phase.

The WebSocket implementation is represented to applications by instances of the WebSocketContainer class. Each WebSocketContainer instance carries a number of configuration properties that apply to endpoints deployed within it. In server deployments of WebSocket implementations, there is one unique WebSocketContainer instance per application per Java VM [WSC 2.1.7-1]. In client deployments of WebSocket implementations, applications obtain instances of the WebSocketContainer from the ContainerProvider class.

The class level @ServerEndpoint annotation indicates that a Java class is to become a WebSocket endpoint at runtime. Developers may use the value attribute to specify a URI mapping for the endpoint. The encoders and decoders attributes allow the developer to specify classes that encode application objects into WebSocket messages, and decode WebSocket messages into application objects.

The method level @OnOpen and @OnClose annotations allow the developers to decorate methods on their @ServerEndpoint annotated Java class to specify that they must be called by the implementation when the resulting endpoint receives a new connection from a peer or when a connection from a peer is closed, respectively [WSC 2.2.2-1].

In order that the annotated endpoint can process incoming messages, the method level @OnMessage annotation allows the developer to indicate which methods the implementation must call when a message is received [WSC 2.2.3-1].

In order that an annotated endpoint can handle errors that occur as a arising from external events, for example on decoding an incoming message, an annotated endpoint can use the @OnError annotation to mark one of its methods that must be called by the implementation with information about the error whenever such an error occurs [WSC 2.2.4-1].

The ping/pong mechanism in the WebSocket protocol serves as a check that the connection is still active. Following the requirements of the protocol, if a WebSocket implementation receives a ping message from a peer, it must respond as soon as possible to that peer with a pong message containing the same application data [WSC 2.2.5-1]. Developers who wish to send a unidirectional pong message may do so using the RemoteEndpoint API. Developers wishing to listen for returning pong messages may either define a MessageHandler for them, or annotate a method using the @OnMessage annotation where the method stipulates a PongMessage as its message entity parameter. In either case, if the implementation receives a pong message addressed to this endpoint, it must call that MessageHandler or that annotated method [WSC 2.2.5-2].

This section describes the the URI mapping policy for server endpoints.

All server endpoint paths must:

Additionally, URI-template server endpoint paths must:

For a definition of URI segments, see RFC 3986 (Berners-Lee et al. 2005). For a definition of URI-templates, see RFC 6570 (Gregorio et al. 2012).

The WebSocket implementation must compare the normalized - see section 6 of RFC 3986 (Berners-Lee et al. 2005) - incoming URI to the collection of all endpoint paths and determine the best match. The incoming URI in an opening handshake request matches an endpoint path if either it is an exact match in the case where the endpoint path is a relative URI, and if it is a valid expansion of the endpoint path in the case where the endpoint path is a URI template [WSC-3.1.1-1].

An application that contains multiple endpoint paths that are the same relative URI is not a valid application. An application that contains multiple endpoint paths that are equivalent URI-templates is not a valid application [WSC-3.1.1-2].

However, it is possible for an incoming URI in an opening handshake request theoretically to match more than one endpoint path. For example, consider the following case:

The WebSocket implementation will attempt to match an incoming URI to an endpoint path (URI or level 1 URI-template) in the application in a manner equivalent to the following: [WSC-3.1.1-3]

Since the endpoint paths are either relative URIs or URI templates level 1, the paths do not match if they do not have the same number of segments, using '/' as the separator. So, the container will traverse the segments of the endpoint paths with the same number of segments as the incoming URI from left to right, comparing each segment with the corresponding segment of the incoming URI. At each segment, the implementation will retain those endpoint paths that match exactly, or if there are none, those that are a variable segment, before moving to check the next segment. If there is an endpoint path at the end of this process there is a match.

Because of the requirement disallowing multiple endpoint paths and equivalent URI-templates, and the preference for exact matches at each segment, there can only be at most one path, and it is the best match.

Examples

The implementation must not establish the connection unless there is a match [WSC-3.1.1-4].

The default server configuration must be provided a list of supported subprotocols in order of preference at creation time. During subprotocol negotiation, this configuration examines the client-supplied subprotocol list and selects the first subprotocol in the list it supports that is contained within the list provided by the client, or none if there is no match [WSC-3.1.2-1].

In the opening handshake, the client supplies a list of extensions that it would like to use. The default server configuration selects from those extensions the ones it supports, and places them in the same order as requested by the client [WSC-3.1.3-1].

The default server configuration makes a check of the hostname provided in the Origin header, failing the handshake if the hostname cannot be verified [WSC-3.1.4-1].

The default server configuration makes no modification of the opening handshake process other than that described above [WSC-3.1.5-1].

Developers may wish to customize the configuration and handshake negotiation policies laid out above. In order to do so, they may provide their own implementations of ServerEndpointConfig.Configurator.

For example, developers may wish to intervene more in the handshake process. They may wish to use Http cookies to track clients, or insert application specific headers in the handshake response. In order to do this, they may implement the modifyHandshake() method on the ServerEndpointConfig.Configurator, wherein they have full access to the HandshakeRequest and HandshakeResponse of the handshake.

The developer may also implement ServerEndpointConfig.Configurator in order to hold custom application state or methods for other kinds of application specific processing that is accessible from all Endpoint instances of the same logical endpoint via the EndpointConfig object.

The developer may control the creation of endpoint instances by supplying a ServerEndpointConfig.Configurator object that overrides the getEndpointInstance() call. The implementation must call this method each time a new client connects to the logical endpoint [WSC-3.1.7-1]. The platform default implementation of this method is to return a new instance of the endpoint class each time it is called [WSC-3.1.7-2].

In this way, developers may deploy endpoints in such a way that only one instance of the endpoint class is instantiated for all the client connections to the logical endpoints. In this case, developers are cautioned that such a 'singleton' instance of the endpoint class will have to program with concurrent calling threads in mind, for example, if two different clients send a message at the same time.

The default client configuration uses the developer provided list of subprotocols, to send in order of preference, the names of the subprotocols it would like to use in the opening handshake it formulates [WSC-3.2.1-1].

The default client configuration must use the developer provided list of extensions to send, in order of preference, the extensions, including parameters, that it would like to use in the opening handshake it formulates [WSC-3.2.2-1].

Some clients may wish to adapt the way in which the client side formulates the opening handshake interaction with the server. Developers may provide their own implementations of ClientEndpointConfig.Configurator which override the default behavior of the underlying implementation in order to customize it to suit a particular application’s needs.

The value attribute must be a Java string that is a partial URI or URI-template (level-1), with a leading '/'. For a definition of URI-templates, see RFC 6570 (Gregorio et al. 2012). The implementation uses the value attribute to deploy the endpoint to the URI space of the WebSocket implementation. The implementation must treat the value as relative to the root URI of the WebSocket implementation in determining a match against the request URI of an incoming opening handshake request [WSC-4.1.1-2]. The semantics of matching for annotated endpoints is the same as was defined in the previous chapter. The value attribute is mandatory; the implementation must reject a missing or malformed path at deployment time [WSC-4.1.1-3].

For example,

In this case, a client will be able to connect to this endpoint with any of the URIs

However, were the endpoint annotation to be @ServerEndpoint("/bookings/SallyBrown"), then only a client request to /bookings/SallyBrown would be able to connect to this WebSocket endpoint.

If URI-templates are used in the value attribute, the developer may retrieve the variable path segments using the @PathParam annotation, as described below.

Applications that contain more than one annotated endpoint may inadvertently use the same relative URI. The WebSocket implementation must reject such an application at deployment time with an informative error message that there is a duplicate path that it cannot resolve [WSC-4.1.1-4].

Applications may contain an endpoint mapped to a path that is an expanded form of a URI template that is used by another endpoint in the same application. In this case, the application is valid. Please refer to the previous chapter for a definition of how to resolve the best match in this type of situation.

Future versions of the specification may allow higher levels of URI-templates.

The encoders attribute contains a (possibly empty) list of Java classes that are to act as encoder components for this endpoint. These classes must implement some form of the Encoder interface, have public no-arg constructors and be visible within the classpath of the application that this WebSocket endpoint is part of. The implementation must create a new instance of each encoder per connection per endpoint which guarantees no two threads are in the encoder at the same time. When sending an application object using the RemoteEndpoint API that is of a type that matches (same class or a sub-class) the parameterized type of the Encoder, the implementation must attempt to encode the object using the matching Encoder [WSC-4.1.2-1].

The decoders attribute contains a (possibly empty) list of Java classes that are to act as decoder components for this endpoint. These classes must implement some form of the Decoder interface, have public no-arg constructors and be visible within the classpath of the application that this WebSocket endpoint is part of. The implementation must create a new instance of each encoder per connection per endpoint. The implementation must attempt to decode WebSocket messages using the decoder in the list appropriate to the native WebSocket message type and pass the message in decoded object form to the WebSocket endpoint [WSC-4.1.3-1]. On Decoder implementations that have it, the implementation must use the willDecode() method on the decoder to determine if the Decoder will match the incoming message [WSC-4.1.3-2].

The subprotocols parameter contains a (possibly empty) list of string names of the subprotocols that this endpoint supports. The implementation must use this list in the opening handshake to negotiate the desired subprotocol to use for the connection it establishes [WSC-4.1.4-1].

The optional configurator attribute allows the developer to indicate that they would like the WebSocket implementation to use a developer provided implementation of ServerEndpointConfig.Configurator. If one is supplied, the WebSocket implementation must use this when configuring the endpoint [WSC-4.1.5-1]. The developer may use this technique to share state across all instances of the endpoint in addition to customizing the opening handshake.

The encoders parameter contains a (possibly empty) list of Java classes that are to act as encoder components for this endpoint. These classes must implement some form of the Encoder interface, have public no-arg constructors and be visible within the classpath of the application that this WebSocket endpoint is part of. The implementation must create a new instance of each encoder per connection per endpoint which guarantees no two threads are in the encoder at the same time. When sending an application object using the RemoteEndpoint API that is of a type that matches (same class or a sub-class) the parameterized type of the Encoder, the implementation must attempt to encode the object using the matching Encoder[WSC-4.2.1-1].

The decoders parameter contains a (possibly empty) list of Java classes that are to act as decoder components for this endpoint. These classes must implement some form of the Decoder interface, have public no-arg constructors and be visible within the classpath of the application that this WebSocket endpoint is part of. The implementation must create a new instance of each encoder per connection per endpoint. The implementation must attempt to decode WebSocket messages using the first appropriate decoder in the list and pass the message in decoded object form to the WebSocket endpoint [WSC-4.2.2-1]. If the Decoder implementation has the method, the implementation must use the willDecode() method on the decoder to determine if the Decoder will match the incoming message [WSC-4.2.2-2].

The optional configurator attribute allows the developer to indicate that they would like the WebSocket implementation to use a developer provided implementation of ClientEndpointConfig.Configurator. If one is supplied, the WebSocket implementation must use this when configuring the endpoint [4.2.3-1]. The developer may use this technique to share state across all instances of the endpoint in addition to customizing the opening handshake.

The subprotocols parameter contains a (possibly empty) list of string names of the subprotocols that this endpoint is willing to support. The implementation must use this list in the opening handshake to negotiate the desired subprotocol to use for the connection it establishes [WSC-4.2.4-1].

The maxMessageSize attribute allows the developer to specify the maximum size of message in bytes that the method it annotates will be able to process, or -1 to indicate that there is no maximum. The default is -1.

If an incoming message exceeds the maximum message size, the implementation must formally close the connection with a close code of 1009 (Too Big) [WSC-4.7.1-1].

These are errors raised during the deployment of an application containing WebSocket endpoints. Some of these errors arise as the result of a container malfunction during the deployment of the application. For example, the container may not have sufficient computing resources to deploy the application as specified. In this case, the container must provide an informative error message to the developer during the deployment process [WSC-5.2.1-1]. Other errors arise as a result of a malformed WebSocket application. Chapter 4 provides several examples of WebSocket endpoints that are malformed. In such cases, the container must provide an informative error message to the deployer during the deployment process [WSC-5.2.1-2].

In both cases, a deployment error raised during the deployment process must halt the deployment of the application, any well formed endpoints deployed prior to the error being raised must be removed from service and no more WebSocket endpoints from that application may be deployed by the container, even if they are valid [WSC-5.2.1-3].

If the deployment error occurs under the programmatic control of the developer, for example, when using the WebSocketContainer API to deploy a client endpoint, deployment errors must be reported by the container to the developer by using an instance of the DeploymentException [WSC-5.2.1-4]. Containers may choose the precise wording of the error message in such cases.

If the deployment error occurs while deployment is managed by the implementation, for example, as a result of deploying a WAR file where the endpoints are deployed by the container as a result of scanning the WAR file, the deployment error must be reported to the deployer by the implementation as part of the container specific deployment process [WSC-5.2.1-5].

All errors arising during the functioning of a WebSocket endpoint must be caught by the WebSocket implementation [WSC-5.2.2-1]. Examples of these errors include checked exceptions generated by Decoders used by the endpoint and runtime errors generated in the message handling code used by the endpoint. If the WebSocket endpoint has provided an error handling method, either by implementing the onError() method in the case of programmatic endpoints, or by using the @OnError annotation in the case of annotated endpoints, the implementation must invoke the error handling method with the error [WSC-5.2.2-2].

If the developer has not provided an error handling method on an endpoint that is generating errors, this indicates to the implementation that the developer does not wish to handle such errors. In these cases, the container must make this information available for later analysis, for example by logging it [WSC-5.2.2-3].

If the error handling method of an endpoint itself is generating runtime errors, the container must make this information available for later analysis [WSC-5.2.2-4].

A wide variety of runtime errors may occur during the functioning of an endpoint. These may including broken underlying connections, occasional communication errors handling incoming and outgoing messages, or fatal errors communicating with a peer. Implementations or their administrators judging such errors to be fatal to the correct functioning of the endpoint may close the endpoint connection, making an attempt to informing both participants using the onClose() method. Containers judging such errors to be non-fatal to the correct functioning of the endpoint may allow the endpoint to continue functioning, but must report the error in message processing either as a checked exception returned by one of the send operations, or by delivering a SessionException to the endpoint’s error handling method, if present, or by logging the error for later analysis [WSC-5.2.3-1].

WebSocket endpoints running in the Jakarta EE platform must have full dependency injection support as described in the Jakarta Contexts and Dependency Injection specification (Jakarta CDI Team, 2020). WebSocket implementations part of the Jakarta EE platform are required to support field, method, and constructor injection using the jakarta.inject.Inject annotation into all WebSocket endpoint classes, as well as the use of interceptors for these classes [WSC-7.1.1-1]. The details of this requirement are laid out in the Jakarta EE Platform Specification (Jakarta EE Platform Team, 2020), section EE.5.2.5, and a useful guide for implementations to meet the requirement is location in section EE.5.24.